VSKI v0.18.0
Connectors are now a first-class platform feature. A definition is a declarative provider manifest, a connector is one configured instance of it, and an account is an authorized credential. One generic engine handles OAuth grants, API keys, basic passwords, custom headers, and public APIs. Provider tokens stay on the server: pipelines, plugins, and triggers call through an authenticated proxy instead of holding credentials.
Definitions are data. Nothing is built into the binary, so the provider catalog is exactly what your IaC declares and the dashboard shows.
SDKs: @vski/sdk 2.11.0 and vski-sdk 0.20.0.
Upgrade notes:
- Four system collections (
_connector_definitions,_connectors,_connector_accounts,_connector_oauth_states) are created automatically on start. Existing collections are untouched. - Existing deployments start with an empty definition catalog. Apply
connectorDefinitionsbeforeconnectors;vski applyalready orders definitions first. - OAuth providers need
<server>/api/connectors/oauth/callbackas their registered callback. SetPUBLIC_URLwhen the server is behind a proxy that does not forward the public host. - Accounts are connected interactively and are not IaC data. Their credentials can reference entries in the encrypted secrets store.
- Connector management endpoints require an admin. The request proxy
requires the
workflowsrole; admins also pass.
Definitions and IaC
Section titled “Definitions and IaC”connectorDefinitions and connectors are global IaC kinds. vski plan,
vski apply, and vski pull round-trip them, with definitions applied
before connectors. vski pull writes connector-definitions.yaml and
connectors.yaml.
A definition declares:
api: base URL, exact allowed hosts, default headers, header fields, auth scheme, and read-only mode.oauth: static client, authorization and token URLs, PKCE, token auth style, form or JSON token requests, scopes, extra auth and refresh params, token refresh, and the connect-time form.key: credential label, connect-time form, and auth scheme.account: profile URL and JSON paths for the remote account id, label, and avatar. It labels OAuth accounts after the grant completes.name,description,icon,docs, and free-formmetadata.
api.baseUrl and api.allowedHosts accept {field} placeholders filled from
connect-time values, so one definition can target per-account sites without
giving up the host allow-list. api.readOnly rejects every method except
GET and HEAD.
Auth schemes cover bearer, header, query, basic, and none. A
custom-header connector declares its api.headerFields; a basic connector
names the form field used as the username.
Definition ids match [a-z0-9][a-z0-9-]{0,63}. OAuth registration is static:
the client id and secret belong to the connector config. Invalid definitions
fail before anything is written.
Accounts and secrets
Section titled “Accounts and secrets”- OAuth: start a connection with
POST /api/connectors/{id}/connect. The returned authorize URL carries a single-use state that expires after 10 minutes. The callback exchanges the code, stores the encrypted grant, fetches the account profile, and returns to the dashboard. Access tokens refresh automatically when an expiry is known, a refresh token is present, and the definition enablesrefresh. - API key and basic password: connect with a token, a token secret, or form values. Basic auth combines the username form field with the token.
- Custom headers: each declared header is collected per account and can come from a secret.
- None: public APIs need no account.
tokenSecret, valueSecrets, and headerSecrets name entries in the
encrypted VSKI secrets store and resolve at request time. Rotating a stored
secret updates every account that references it without rewriting the account
or the connector config. Credential values never appear in account responses,
connector configs, pipeline output, or run events.
A connector can hold several accounts. Requests select one by id or name, or fall back to the first active account.
Pipelines, plugins, and triggers
Section titled “Pipelines, plugins, and triggers”Pipelines gain a connector step. It resolves account, path, url,
headers, and body as templates, attaches the account credential
server-side, and returns {status, headers, body}. Non-2xx provider responses
fail the step so the usual retries and onError behavior apply. The timeout
defaults to 30 seconds and is capped at 120.
{ "id": "projects", "type": "connector", "connector": "internal", "account": "{{input.account}}", "method": "GET", "path": "/v1/projects?limit=50" }Because account is templated, one pipeline definition can run against any
connected account supplied as run input, including accounts for different
sites of the same provider.
Plugins and external systems use POST /api/connectors/{id}/request with an
API key that carries the workflows role. The proxy applies the stored
credential, enforces the host allow-list, and returns the provider status,
headers, and body. The proxy call itself answers 200; a provider rejection
is reported in status, and transport or configuration failures return
4xx or 5xx with the reason.
A connector is bound to its declared hosts. Only api.allowedHosts entries
and the resolved base URL host are reachable, matched exactly with no
wildcards. A single account at a site root can serve several APIs on that
host, such as Confluence under /wiki/api/v2/... and Jira under
/rest/api/3/....
Connector dashboard and SDKs
Section titled “Connector dashboard and SDKs”- The Connectors page lists configured connectors with auth mode, account count, status, base URL, and connect, accounts, test, and delete actions.
- The add and edit wizard walks provider, auth, endpoints, credential rules, connect-time form, and review as separate steps. Every provider comes from the applied definition catalog or the custom definition; no provider list is hardcoded in the UI.
- The account dialog renders the definition form and supports stored-secret references. The test dialog sends an authenticated provider path and shows the status and response.
- Dialog actions sit in a sticky footer outside the scrolling body.
SDK support:
- TypeScript
@vski/sdk2.11.0 addsclient.connectorswith definitions, configs, accounts, OAuth start, and the request proxy. - Python
vski-sdk0.20.0 addsclient.connectorsand IaC loading, diffing, applying, and pulling for both connector kinds. The synchronous client exposes the same namespace.
Agent-facing dashboard
Section titled “Agent-facing dashboard”The dashboard can be handed a connection and opened on a single surface, which is what an agent does when a human has to act: approve a run, filter records, run a pipeline.
GET /connect?endpoint=...&token=...&path=...saves the deployment URL and its bearer token and forwards topath. Without a token it goes to login with the target kept as?next=, so the user lands where they were headed. The endpoint is normalized to an http(s) origin,nextstays dashboard-relative, and a stale saved API key is cleared: the dashboard’s admin endpoints reject API keys andX-API-Keyis checked beforeAuthorization, so a leftover key would shadow the token./w/...routes render the same pages inside a chrome-less shell: no sidebar, connection badge, breadcrumbs, feature chips, or desktop titlebar, with dense padding. The page keeps its own actions — record create, edit, delete, run, save, approve, reject — because widget mode strips navigation, never capability.- Every surface has a widget route:
/w/overview,/w/collections/:name(and/stats,/:id,/create),/w/workflows,/w/workflows/:runId,/w/signals,/w/pipelines(and/:name),/w/connectors,/w/cron,/w/gates,/w/webhooks,/w/api-keys,/w/secrets,/w/plugins,/w/migrations,/w/graphs(and/:name,/create),/w/logs,/w/sql,/w/settings(and/auth). - Widget query params are
filter(list and collection tables),sort(-fieldfor descending),page,perPage, anddb(/w/collections,/w/graphs,/w/sql;databaseis accepted as an alias on the SQL console), plusstatus/collectionfor webhook logs.action=createopens the create dialog on a list page (or the record form on a collection), andaction=runopens the run dialog in the pipeline editor./w/sqlalso takessqlto pre-fill the query andexecute=trueto run it on load and show the results, so an agent can hand over a query and its outcome in one link. Links stay inside/w, and the surface name is the document title, so the browser tab identifies the widget. - The widget gains no leftover dashboard space: the SQL results modal fills the viewport instead of leaving the sidebar’s column, and the pipeline canvas drops React Flow’s minimap (it duplicated the canvas and took room from the step palette).
- The Harness Account panel gains Open dashboard:
Vski.dashboard(GET /api/vski/connections/:id/dashboard) builds a one-shot/connectURL signed with the selected slot’s bearer token and opens it externally. An API-key slot yields a URL without a token, because the dashboard cannot be signed in with one.
Signal approvals
Section titled “Signal approvals”A run parked on a signal is a human decision waiting to happen, so the dashboard treats it as a first-class surface.
/signals(and the/w/signalswidget) lists every waiting signal across the deployment: pipelinesignalsteps and code workflows parked inwaitForSignal. Plugin-managed pipeline steps also park on a signal, but that is the plugin’s wake-up, so the inbox hides it.- Each entry renders approve or reject with an optional reason and records
the signed-in admin as
by. Delivery uses a single-use workflow hook: create it with a random token,POST /api/workflows/hooks/:token(emitssignal_receivedand requeues the run), then delete the hook. The payload is{ ok, by, reason?, signalId? }. The run page renders the same form above its timeline. - A wait can carry a description:
descriptionon a pipelinesignalstep, or the option onwaitForSignal/wait_for_signal. It is rendered with the run context when the step parks and carried in thesignal_waitingpayload, so the inbox and the run say what is being approved. Rendering is best-effort: an unresolved template path is kept as written rather than failing the run. The pipeline builder edits it in the signal step inspector. - Harness automation notifications carry the prompt as their body ahead of
the run reference, and
GET /repos/:name/signalsreturns it asdescription.
Tests and docs
Section titled “Tests and docs”- A new end-to-end suite covers definition storage, encrypted accounts, the authenticated proxy, a pipeline step with a templated account, stored secret references, and rejection of hosts outside the allow-list.
- The connector engine and pipeline step have unit coverage for auth scheme application, OAuth refresh, stored secret resolution, templating, non-2xx failures, and host rejection.
- Managed providers were validated end to end: Google over OAuth and Atlassian over one account token serving both Confluence and Jira.
- Executor tests cover the signal description payload and its
unresolved-template fallback; harness tests cover the description reaching
Signal.Pendingand the notification body. - The approval flow was validated against a running deployment: a parked
pipeline run and a
waitForSignalrun both appear in the inbox, a response writessignal_receivedwith{ok, by, reason, signalId}, the run resumes and completes, and the single-use hook is gone afterwards. Every widget route was opened against a running deployment — tables, editors, and config pages — checking for the compressed header, no sidebar or connection badge, the surface title in the tab, the filter andactionparams, and links that stay under/w; the normal routes were checked unchanged. - The wiki gains a Connectors page linked from the sidebar, and the IaC and Pipelines pages document the new kinds and step. The Workflows and Pipelines pages document signal descriptions.