Autonomous agent onboarding should begin with a locked vault

Autonomous agents should earn access in stages. If you start by handing an agent a production token and asking it to "be careful," you have skipped the only part of setup that teaches you how the controls behave under pressure.

A first-day path should begin with a vault that denies everything, move through one low-risk HTTP action, then add SSH, then add approval on every use for credentials that deserve it. Finish by verifying the audit record while the run is still fresh in your mind. The order matters because each stage isolates a different failure.

The goal is not to make an agent useful as quickly as possible. The goal is to learn exactly what it can do, what you must approve, what it records, and how to stop it before you connect it to work that has consequences.

Begin with a vault that refuses every action

Your first successful test should be a denial. A locked vault must refuse an agent action even if the agent has a perfectly reasonable request and even if the credential is already configured.

That sounds backwards until you have watched an agent retry a failed action. Agents do not experience hesitation. If a tool reports that access is unavailable, the agent may try a different endpoint, revise an argument, invoke a related tool, or ask for approval. You want the security boundary to answer before any credential leaves its protected store.

On a Mac, make sure the app is running, but leave the vault locked. Start the agent through its normal development workflow and give it a deliberately harmless request, such as retrieving a test resource from an API you have not yet authorized.

The expected result is simple: the request does not run. Do not work around the denial by pasting the token into an environment variable, a shell profile, a prompt, a project file, or an agent configuration file. That workaround teaches the wrong lesson because it turns your first test into a conventional secret-handling problem.

Write down what the agent reported. You are checking two things:

• The agent can reach the action gateway through its MCP connection.
• The vault gate stops the action while locked.
• No secret appeared in the agent transcript, terminal output, or tool arguments.

The distinction between an unavailable credential and a locked vault matters. An unavailable credential usually means you have a setup problem. A locked vault means the setup works and access is intentionally closed. If you treat both failures as "the token did not work," you will eventually disable the control that was protecting you.

Sallyport uses this as the first control in its decision ladder: while the vault is locked, every action is denied. On supported Mac hardware, the vault gate uses Secure Enclave and Touch ID rather than asking the agent to prove anything about itself.

Connect the agent without handing it a secret

An agent needs an action path, not a copy of a credential. That is the rule that keeps a useful automation run from becoming an uncontrolled secret distribution event.

Configure the MCP-capable agent to use the bundled stdio shim:

sp mcp

The shim is a regular MCP server. The agent talks to it, asks to perform an HTTP or SSH action, and receives a result. The credential stays in the encrypted vault inside the app. The agent does not receive a plaintext token, a substitute token, or a secret-shaped placeholder it can later misuse.

This is a sharper boundary than many teams draw. They often say, "the agent has limited access," when they actually mean the agent has a token in its environment with limited permissions. Those are different systems.

With an environment variable, every process that can read the environment may be able to copy the secret. A shell history entry, debug log, crash report, child process, prompt export, or pasted terminal transcript can extend its lifetime. With an action gateway, the agent can ask for a specific action, but it cannot inspect the credential material that authorizes it.

Before you unlock anything, inspect the agent configuration for the usual leaks:

• Remove tokens from .env files, shell startup files, agent instructions, and project documentation.
• Do not add a credential to a tool argument merely because a tool supports a token field.
• Avoid giving the agent permission to read the same password manager, secret file, or cloud credential directory you are trying to protect.
• Keep your first agent run separate from any terminal session that has privileged environment variables loaded.

This is also where developers make a popular but bad recommendation: "Use a temporary token first, then harden it later." A temporary token is still a secret once it enters an agent context. Use a temporary credential for limited impact, yes. Do not use it as permission to abandon the boundary between the agent and the secret.

Make one boring HTTP request before anything else

Your first allowed action should be one HTTP request with a credential that has a narrow purpose. Read-only is preferable. A test account is better. An endpoint that returns a known, non-sensitive object is best.

Choose a request you can verify independently. Good examples include reading a test repository's metadata, retrieving a sandbox profile you created, or calling a status endpoint tied to a non-production account. Avoid endpoints that list real customers, source code, billing data, or broad account settings. A successful read can still disclose more than you intended.

Set up the HTTP credential in the vault using the authentication form the service expects: bearer authentication, basic authentication, or a custom header. Keep the credential label clear enough that you will recognize it in an approval card later. "Test API read" is better than "token 2." Your future self should not have to open a password manager to know whether one click is safe.

Now unlock the vault and start a fresh agent process. Per-session authorization is on by default, so the first action from that new process should present an approval card. Read the code-signing authority shown there before you approve.

Do not reduce this check to "I recognize the agent name." A familiar command name can be launched by an unexpected wrapper, a copied binary, or a different development tool. The approval card leads with the process's code-signing authority because the process that requested access matters more than the natural-language task it claims to be doing.

Approve the run only if all of these are true:

1. You started the agent process yourself.
2. The signing identity is what you expected for that process.
3. The requested credential has the narrow scope you intended.
4. The request is the one you asked the agent to make.

Then have the agent make exactly one call. Compare the returned result with a manual request you make outside the agent workflow. You are not proving that HTTP works. You are proving that the agent can request an action, the gateway can inject the stored credential, and the result can return without exposing the credential itself.

A useful first-day record is short:

Credential: Test API read
Agent task: Retrieve one known test object
Expected result: Object identifier and status only
Manual comparison: Same identifier and status
Unexpected data returned: None

If the response includes more fields than you expected, stop there. Do not tell the agent to summarize the extra data and continue. Reduce the API scope, use a smaller test object, or select a narrower endpoint. The first HTTP call should create confidence through containment, not through an impressive result.

Session approval is permission for a run, not a blank check

Per-session authorization answers a specific question: do you approve this agent process for the lifetime of this run? It does not answer whether every credential or every requested action deserves the same treatment.

Once you approve a run, the agent may make more than one call before it exits. That is useful when you are supervising a coherent task, such as reading test metadata and generating a local report. It is risky when the run has an open-ended prompt, can spawn related work, or has access to credentials with different consequences.

Treat a session as a bounded work unit. Start it for one task. Watch the first few actions. End it when that task is done. Start a new process for the next distinct task so you get another authorization decision.

The Sessions journal should support this habit. It records agent runs, and you can revoke a run instantly. Use revoke when the agent starts drifting, when you realize you approved the wrong process, or when the task changes shape halfway through.

Here is a failure pattern worth recognizing. You ask an agent to "check the test API and fix any obvious issues." It begins with a harmless GET request. You approve the session. It finds a configuration mismatch, sees a write endpoint among the available actions, and decides the obvious fix is to update the setting. The credential may permit it, and the original approval may still cover the run.

Nothing in that story requires a malicious agent or a broken tool. The fault is the task boundary. You gave one session a discovery phase and a remediation phase, then expected your original approval to carry the same meaning through both.

Split the work instead. Approve a read-only discovery session. Review its findings. Then start a separate run for a proposed change, preferably using a different credential with narrower write permission. Approval becomes meaningful when it tracks a unit of work you can describe in one sentence.

Add SSH only after the HTTP boundary feels ordinary

SSH is not "HTTP, but for servers." It carries a larger set of consequences because a successful connection can run arbitrary commands, inspect files, alter permissions, and move data through channels that a narrow API never exposes.

Start with a disposable host or an isolated development machine. Create a remote account that has no production access, no shared credentials, and no reason to touch your home directory or cloud configuration. Put a harmless file on that host with a known line of text. The agent's first SSH task should retrieve that line and nothing else.

Sallyport routes SSH actions through its bundled stateless Go helper, sp-ssh. The agent requests the action through the same gateway model, while the stored SSH credential remains in the vault rather than becoming a private key file the agent can read.

The first SSH exercise should be deliberately narrow:

Host: isolated development host
Remote account: restricted test account
Allowed task: Read one known text file
Expected response: The exact line placed in that file
Stop condition: Any attempt to inspect other paths or run a second command

Do not begin with "run diagnostics." That phrase is too broad. Diagnostics often means process listings, network configuration, package inventories, log files, home directories, and application configuration. A capable agent will interpret the request broadly because broad interpretation is often how it finishes a task.

Watch for an operational mistake that shows up often: developers test SSH with an account that is convenient rather than safe. It has access to a familiar host, perhaps through an existing personal key, so the test is quick. Then the agent's first SSH experience includes repositories, deployment credentials, shell history, configuration files, and whatever else that account can read. You have learned that the tunnel works, but you have learned nothing useful about containment.

A restricted test account makes the failure legible. If the agent asks for an unexpected path, you can see the attempted action in the journal and deny or revoke without wondering whether it has already found a more sensitive file.

Per-use approval belongs on consequential credentials

Per-use approval asks you to confirm every use of one credential. Set that flag before you try a credential that can change a system, access sensitive material, or reach a host where one shell command can have a wide effect.

Developers often resist this because repeated prompts feel inefficient. They are right about the cost. A prompt on every low-risk read will train you to click through prompts without reading them. That is approval fatigue, and it makes the control worse than absent because it creates false confidence.

Use the per-use setting where each action needs a fresh human decision. Good candidates include credentials that can:

• create, modify, or delete remote resources;
• read personal, customer, financial, or security-sensitive records;
• invoke administrative API methods;
• open SSH access to a shared development, staging, or production-adjacent machine;
• trigger a deployment, job, workflow, or external notification.

Keep low-risk test reads under session approval while you learn the workflow. Put a per-use gate on the next credential you add that has a real consequence. Then give the agent a task that requires two separate calls, such as reading a test setting and proposing, but not applying, a change. Confirm that you must approve each use when the credential is flagged that way.

The distinction here is important. Per-session approval asks whether a particular process may act during this run. Per-use approval asks whether this particular credential may be used right now. One is about process identity and run lifetime. The other is about the consequence attached to one stored secret. Treating them as interchangeable leads teams either to approve too broadly or to prompt so often that nobody reads the card.

When the prompt appears, inspect more than the credential label. Check the action, destination, and whether the agent's current task still justifies it. If it does not, deny the use and ask the agent to explain its plan in plain language before you approve anything else.

The activity journal is where surprises become evidence

A session record tells you which agent run received approval. An activity record tells you what happened inside that run. You need both because a clean-looking process can still make a bad call, and a suspicious call means little if you cannot connect it to the run that caused it.

After the HTTP test, open the Activity journal and read every individual call. Then do the same after the SSH test. Compare the record with your written exercise: the expected endpoint or host, the expected action, and the expected result. You are training yourself to spot a mismatch while it is still easy to explain.

Pay particular attention to calls that look harmless in isolation but do not fit the task. A metadata endpoint might reveal account structure. A host probe might lead to a wider command. A retry might be harmless, or it might indicate that the agent changed parameters after the first response failed. Context comes from the session and the sequence, not from one line viewed alone.

Do not rely on the agent's narration as your record. Agents can summarize accurately, omit a detail, misunderstand a tool response, or produce a polished explanation for an action you would not have approved. The journal is for checking what happened, not for grading the prose around it.

This is also the point where instant revoke earns its place. If you see the agent shift from the agreed task to exploration, revoke the session first. You can sort out whether the call was benign after you have stopped further actions. Waiting for a complete explanation is sensible in a meeting; it is a poor response to an active process with credentials.

Verify the audit chain before you need it in an argument

An audit record is useful only if you can detect tampering with the record itself. Reading a list of events tells you what the interface currently displays. Verification tells you whether the encrypted audit log's hash chain still checks out.

Run this after the first two exercises:

sp audit verify

Sallyport can verify the hash chain offline over ciphertext, so this check does not require access to the vault secret. That property is practical during an investigation. You can check the integrity of the record without first unlocking the same store that controls agent actions.

Run the command once while everything is calm. Note where you keep the result for a change, test, or incident. Then repeat it after a deliberately denied action, an approved HTTP call, and an approved SSH call. You are checking a sequence with known events, which makes a later unexpected verification result easier to recognize.

Do not wait until a serious production question to discover who can run the command, where the logs live, or whether your team knows the difference between a session record and an individual call. That is the common failure. Teams install logging, trust that it exists, and only open it after someone asks, "Who approved this?" By then they are trying to learn the tool and reconstruct the event at the same time.

The audit log is projected into the Sessions and Activity journals from one write-blind encrypted, hash-chained record. That gives you two views for operations without making those views the only evidence you can inspect.

Make the first week harder than the first demo

A polished demo ends when the HTTP request succeeds. A usable onboarding path continues until you have denied an action, approved a bounded run, revoked one on purpose, inspected individual calls, exercised SSH on an isolated host, used per-use approval, and verified the audit chain.

Keep the first week small enough that you can explain every action. Add only one new credential or capability at a time. If a new setup needs several exceptions, broad scopes, and a prompt you cannot interpret quickly, it is not ready for an autonomous agent.

The practical test is blunt: when the agent asks to act, can you tell who is asking, which stored credential would be used, what external system would receive the action, and where you would look afterward? If any answer is vague, return to the earlier stage and narrow the test.

That is slower than copying a token into a configuration file. It is also how you avoid discovering, at 2 a.m., that your first real agent run was the moment your credential controls stopped being controls at all.