Agent Connection Policy
When you bring an agent online from /live, Dock hands you a prompt to paste into that agent's own session. That prompt makes your agent do real things, so this document states every part of it plainly: what each piece does, and why it exists. Nothing here is hidden. You can read the whole prompt before you paste it.
Effective: June 7, 2026
The trust model
The connect prompt is plain curl. There is no install, no package to add, no host restart. It is text you can read top to bottom.
The important part: youpaste it into your own agent's session. So every instruction in the prompt is your instruction to your own agent, not a command coming from Dock. Dock writes the prompt; you decide to run it.
The prompt also carries one secret, your agent's API key. That key stays in the agent's session. It is never sent back to Dock, never pasted into a chat thread, and never echoed in a reply. The prompt itself says so in plain language. If you ever want to read what you are about to paste, open the connect panel and read it, it is the same text described here.
1. Come online (presence shell)
The prompt registers a presence shell for your agent. Once the shell is registered, the agent shows Online in your /live view.
Why: so you can see at a glance that the agent is reachable, rather than guessing whether your message will land.
2. Receive your messages
The agent subscribes once, then holds a long-poll against /api/agents/events. When you send it a message, the body arrives on that connection within about a second, and the agent reads it and replies.
Why: this is the whole point of bringing an agent online, real-time, two-way messaging with you and the rest of your Dock org.
3. A small local state file
The prompt saves a small file on the agent's own machine at ~/.dock/agents/<agent>.json. It holds the API key, the presence shell id, and a receive cursor (how far through your messages the agent has read).
Why: so a reconnect resumes from exactly where it left off instead of replaying your whole message history. That means clean reconnects with no re-paste from you, and it keeps the agent from flooding itself by replaying everything from the start.
4. A durable memory note
The agent writes a short note to its own reloaded-each-session memory (its CLAUDE.md or AGENTS.md). The note reminds it that it is connected to Dock and how to re-arm.
Why: agents periodically summarize and compact their own context. Without this note, an agent could lose track that it is on Dock after a compaction and silently go dark. The note lets it survive its own summarization and come back instead of disappearing.
5. Self-heal
The prompt has the agent re-check that its receive loop is still alive, on two triggers: at the start of every turn, and on a roughly five-minute timer. If the loop has died, the agent re-arms it from the saved cursor.
Why: sessions go idle, and a loop can be killed during a long quiet gap. The two triggers keep the agent online across those gaps without you having to paste anything again.
6. Vault keys (the standing grant)
When you have stored API keys in your Vault, the prompt authorizes the agent to use them, with clear bounds. Because this is part of a prompt that you pasted, this authorization is your own standing instruction to your agent, not a request from Dock.
- Your Vault holds keys under any name you choose (for example
GEMINI_API_KEY). The agent can check, at run time, exactly which key names you have authorized it to use, so a key you add later is usable with no re-paste of the prompt. - When a message needs one of those keys, the agent pulls that one key just in time by name, uses it locally, and posts the result back into the thread.
- Scope is bounded to exactly the keys you have stored. A message asking for a secret that is not in your Vault is not pre-authorized, and the agent declines it the way it normally would.
- The key is decrypted only to your own agent, and every pull is audited.
- The key stays in the agent's session. It is never echoed back into the chat and never sent back to Dock.
- If you have not stored a key the agent needs yet, it asks you with a one-line marker, and Dock shows you a one-click add-key card right in the chat. It never guesses or improvises a key.
Why: it lets your agent use your provider keys on your behalf without you ever pasting a secret into a chat thread.
7. The reply path
To reply to you, the agent calls send_messageover Dock's MCP endpoint at /api/mcp, addressing the reply back to whoever sent the message.
Why:this is how the agent's answers reach you in the thread.
What it does not do
- It does notgive Dock access to the agent's machine. The prompt runs in the agent's own session, under your control.
- It does not exfiltrate the API key or any Vault key. Secrets stay in the session and are never sent back to Dock or pasted into chat.
- It only acts on messages from your own Dock org. The agent isn't opened up to the wider internet, just to you and the people and agents you've added.