Skip to content
Palladin.ioDocumentation
PL
Docs/Developer docs

Connect an agent

One procedure for environments that support CLI or MCP.

1.025.10.2026Markdown ↗

1. Check prerequisites

You need a Palladin account, the ability to approve an Agent, and access to the environment running the runtime. Installing software, registering an Agent, and granting entry access are separate steps.

palladin --version
palladin doctor
palladin agents list

doctor checks the local runtime boundary without opening identity. It does not prove an active connection or entry permissions. If the CLI is missing, see installation.

2. Create and connect an agent

We recommend pairing through the web panel. The panel prepares the configuration and you approve the connection in your browser. You do not need to pass an API key to the CLI manually.

  1. Open Agents and select the + button (“Add Agent”) above the list.
  2. Give your agent the message generated by the panel. It contains the configuration and connection instructions.
  3. The agent starts pairing. Open the indicated page and approve the connection.
  4. Check the agent in the panel and its CLI status.

If you run the commands yourself, use the profile and setup data from the panel:

palladin --id <profile> pair-agent --host <api-origin> --setup-descriptor '<descriptor-from-panel>'
palladin --id <profile> status

The setup descriptor is not an API key. Do not give a model your account password, API key, or recovery key.

Alternative: manual API-key connection

  1. In the panel, open Settings → API Keys, select + (“Generate API Key”), enter a name, and submit the form. Make sure you are working in the correct organization. Its full value is shown only once.
  2. Create a local agent profile. example-agent is an example; choose your own unused name:
palladin agents create example-agent
  1. Connect the profile to the API for the same environment as your panel. Replace <api-origin> with its API origin:
palladin --id example-agent connect --host <api-origin>

The CLI requests the API key through a masked prompt. Enter it directly in the terminal, never in an agent conversation, command argument, or environment variable.

  1. Confirm the connection and check that the agent appears in the panel:
palladin --id example-agent status

The profile holds the agent identity; the API key authenticates the organization connection. Connecting does not grant entry access — that requires a separate grant.

For automation, the CLI accepts a key through protected standard input with connect --api-key-stdin. A trusted secret store supplies it; do not place the key in a script or shell history.

If the profile already exists, check palladin --id <profile> status. Do not recreate it or delete its identity to repair an error. Keep using the same profile in the following steps.

3. Use the CLI

CLI is the recommended integration method. Your agent runs terminal commands and selects its profile with --id.

If your application requires MCP, add the server configuration. MCP uses the installed CLI; it does not replace CLI installation or agent pairing.

4. Test without a secret

Create a separate API Key entry named Palladin connection test with the public value palladin-connection-test. Do not use a real key. Find the entry and use the returned identifiers:

palladin --id <profile> search 'Palladin connection test' --json
palladin --id <profile> exec <vault-id> <entry-id> --reason 'Verify the connection using a non-secret test entry' --env PALLADIN_TEST=value --wait 2m -- node -e 'process.exit(process.env.PALLADIN_TEST === "palladin-connection-test" ? 0 : 1)'

The user approves a narrow Exec grant for the test entry, preferably one use. The process compares the value and returns an exit code without printing anything. In MCP, call exec_with_credential with these arguments (replace the profile and IDs):

{"profile":"example-agent","vaultId":"<vault-id>","entryId":"<entry-id>","reason":"Verify the connection using a non-secret test entry","wait":"2m","command":["node","-e","process.exit(process.env.CLAW_SECRET === 'palladin-connection-test' ? 0 : 1)"]}

CLAW_SECRET is the current runtime-provided variable name; do not rename it based on product branding.

5. Confirm the outcome

Success requires an active identity, the correct profile, approved access, and a successful test operation. A visible MCP server alone is insufficient. Afterwards, revoke any remaining grant or remove the test entry in the panel if the user does not want to keep it.

This verifies Exec. It does not verify browser readiness or Inject.