Skip to Content
Polyant is open source under AGPL-3.0 — star us on GitHub.
Admin PanelDev Mode

Dev Mode

On this page

Managed services. The dev bridge is available with Polyant managed services.

Dev mode runs tool and hook implementations from a developer’s own machine as if they were part of a live agent. The engine keeps everything else - the real tool context, authorization, governance, audit, conversation state, reply semantics - and asks the laptop only for the result. The source never reaches the engine and is never persisted.

It is an iteration path, not a deployment mechanism. A tool that works this way is not a tool that has shipped.

Who can open one, and where it is switched on

Availability is the intersection of two grants held in the database, exactly as skills and plugins are:

  1. A platform admin grants dev mode to an organization, from the Admin Console.
  2. An organization admin enables it for a workspace, at /organizations/{org}/workspaces/{ws}/settings/dev-mode.

Both start off, and removing either closes the live sessions it covered. The workspace setting appears only once the organization grant exists, and the agent’s Dev mode section only when both halves are present - but that visibility is convenience: the engine rechecks at token issuance and again at the WebSocket handshake, so hiding the page is never what enforces the rule.

There is no deployment switch. Dev mode used to have one, and an installation-wide flag could not express “this customer, that team” - which is the only shape the question ever takes.

An agent whose organization or workspace cannot be resolved gets neither half. The intersection fails closed.

What issuing a token actually grants

Opening a session needs agent.dev:write, which sits at Admin and above. That is deliberately higher than the keys that configure an agent, because the capability is genuinely larger than its name:

  • A session serves real users. It does not open a sandbox beside the agent: while it is open, its tools and hooks run on every conversation of the agent, on every channel, not only the conversations of the person who opened it. Its hooks can halt a turn, inject context, or regenerate or replace the reply a user receives.
  • A dev tool receives the plaintext values of the secrets it declares. Provider keys are not among them: the conversation authenticates through a provider connection, so ctx.apiKeys is withheld from the dev runtime and binding a connection never discloses its key, and the provider keys the upgrade left in the secrets are withheld even when a dev tool declares them. The developer’s machine becomes part of the trusted execution boundary for the duration of the session.
  • Dev tools bypass the agent’s tool allow-list. A declaration carrying a new name is added for the live session; one whose name collides substitutes the equipped implementation. So a session is not a preview of what the agent has been given - it is an administrator adding or replacing behaviour at runtime.

Treat the token itself as a credential able to execute local code with the agent’s context. The plaintext is returned once, at issue, and only its hash is stored; nothing in the panel or the API ever shows it again.

The lifecycle, and what each gesture does

Issue the token from the agent’s Dev mode section, choosing how long it is valid: at most 24 hours, and, when you name no lifetime, the Dev token lifetime installation policy (8 hours by default). Issuing a replacement invalidates the previous token and closes the session it was holding, so re-issuing is the fast way to lock out a machine you no longer trust.

Revoking stays possible after the grant is removed. That is not an oversight: a stale credential must always be cleanable, and tying the revoke to a capability someone just withdrew would leave exactly the tokens you most want gone.

The keepalive rechecks expiry, the token’s current state and the issuer’s permission on every tick, so a revoke issued against one replica stops a session held by another, and a session ends within one tick on every replica once its issuer loses agent.dev:write. A session cannot quietly outlive its credential or the person behind it. A socket that sends more than 500 frames a second is closed, so a leaked token cannot keep a replica busy parsing frames.

The status endpoint reports availability, token state and live-session state as three separate facts, and returns neither the plaintext nor the hash. The issuer’s name is shown only to a caller who may already read the organization’s members; to anyone else the session is present but the issuer is redacted.

The anonymous WebSocket handshake answers every failure with one generic refusal - unknown agent, bad token, missing grant, wrong protocol version all look identical from outside. Distinguishing them would turn the endpoint into an oracle for which agents exist.

Where a live session is visible

A session is not something an operator should have to go looking for:

  • The agent’s Status section raises it at the strongest level the taxonomy has. An open token with nobody connected is a warning; a connected session is reported as broken - not because anything is failing, but because an agent answering with code from a laptop is not an agent in a normal state, even when it works. Only one of the two is reported at a time, since the connected session is the stronger fact about the same window.
  • A turn served by a dev session is badged in the conversation and in the Playground, on the live frame as well as on the stored message, so a surprising answer can be traced to the bridge that produced it rather than to the prompt.
  • Token issue, revoke, session identity and every proxied tool call are written to the audit trail, without the secret payloads. A session opening and closing is also recorded in the organization’s management audit as dev_session.open and dev_session.close, and a tool or hook served by a session carries its devSessionId on its audit rows and on the reply’s provenance.

A reader who lacks agent.dev:write sees no dev checks at all - not a green one. “I could not look” and “nothing is open” are different answers, and the second would be a false all-clear.

Side effects are the caller’s problem

A remote invocation that times out or is cancelled can still finish on the developer’s machine after the engine has thrown its result away. The engine’s half is safe - state and audit writes returned with a failed call are not committed, which preserves the turn’s commit-on-success rule - but the write your tool already made to a third-party system is not something the engine can take back.

Tools that write need idempotency keys or downstream de-duplication. A tool whose effects cannot be made repeatable should say so.

The per-call budget is the Dev-mode tool call installation policy (30 s by default). On expiry the error reaches the model and the socket stays up, so one slow tool does not end the session.

Hooks served by a session

A session can serve hook functions as well as tools. A hook declared by the local runtime enters the pipeline in one of two ways:

  • overrides names a hook function the agent already has configured. The agent’s own hook rows keep deciding the event, the order and the timeout; only the code that runs changes. The executions keep the canonical function name in the audit trail and in the conversation’s hook executions, so a substituted hook stays visible in the telemetry you are watching it with.
  • bindTo runs a new function on an event (with its own order and timeout, up to 120,000 ms) where no configured row exists. The binding lives only as long as the session: it is never written to the agent’s hooks, so a closed session leaves no hook behind that nobody decided on and nobody sees in the Hooks section. Its name must be bare, without a plugin namespace.

A declaration cannot carry both. One with neither is accepted and never runs. A hook served by a session passes the same gates as a deployed one, including the mutatesResponse rule for replaceResponse and regenerate.

Operator workflow

  1. A platform admin grants the organization; an org admin enables the workspace.
  2. Open the agent’s Dev mode section and issue a token with the lifetime you need.
  3. Point the local runtime at the advertised endpoint with that one-time token.
  4. Check that the panel reports the equipped and substituted tools and hooks you expect before sending anything through the agent.
  5. Revoke when you are done.

Exact endpoints and payloads are in the REST API reference. The call timeout and the default token lifetime are installation policies, editable without a redeploy. The protocol version and connection limits live in the engine’s configuration schema and are deliberately not restated here - reading them from the running deployment is the only version that stays true.

See also

Last updated on
PlaygroundActivity