Connect your first agent | AgentTrunk Documentation

Goal: authenticate and find the workspace your agent should use. No production changes are needed.

1. Install the CLI

Use Node.js 22 or newer. The source installation below does not depend on an npm registry release.

1 git clone https://github.com/aadi-labs/agenttrunk-plugins.git
2 cd agenttrunk-plugins
3 npm ci
4 npm run build
5 npm install -g .
6 agenttrunk --help

Review the source before installing it. To avoid a global install, use node dist/cli/index.js in place of agenttrunk from this checkout.

2. Reuse authorization or request approval

If your runtime already supplies AGENTTRUNK_ACCESS_TOKEN, do not print it or start another registration. Continue to step 3.

Otherwise:

1 agenttrunk auth discover
2 agenttrunk auth start --email HUMAN_EMAIL

Replace HUMAN_EMAIL with the authorizing person’s email. Give that person the returned verification link. They sign in and approve access. Then run:

1 agenttrunk auth complete

Enter the approval code through the prompt, not a command argument. Do not obtain it by reading the person’s inbox or browser session. A new human must first create an account and organization.

See authentication for credential storage and cloud runtimes.

3. Select the workspace

1 agenttrunk workspaces
2 agenttrunk scopes --workspace WORKSPACE_ID
3 agenttrunk discover --workspace WORKSPACE_ID --channel production

Use IDs from the responses and choose the workspace intended for this task. Never select the first workspace implicitly. Follow nextCursor where returned, even after an empty page.

An empty successful response is different from an access error. If you are authorized to create a workspace and one is needed:

1 agenttrunk workspace-create --name "Customer support"

Use its returned ID, then list scopes to find General. Do not create a new organization to work around denied access.

4. Upload a prompt to staging

Create a local file named welcome.md containing:

1 # Welcome assistant
2 
3 Greet the user, ask what they want to accomplish, and do not invent account details.

Choose a new context key so this exercise does not replace an existing package:

1 agenttrunk upload --workspace WORKSPACE_ID --scope SCOPE_ID \
2   --key welcome-assistant --title "Welcome assistant" --kind prompt \
3   --file ./welcome.md --path prompts/welcome.md

This writes to staging, not production. Save the returned revision.id. If you cannot publish, request access from your administrator; signing in does not grant every permission.

5. Read exactly what you uploaded

1 agenttrunk inspect --workspace WORKSPACE_ID --key welcome-assistant --ref REVISION_ID
2 agenttrunk read --workspace WORKSPACE_ID --key welcome-assistant \
3   --ref REVISION_ID --path prompts/welcome.md

Replace REVISION_ID with the returned 64-character revision ID. The CLI checks the file against its manifest before returning it. You should see the welcome instructions you just uploaded.

You now have a reproducible context read. Give that revision ID to your harness and retain it with the run. Production has not changed.

Next steps

Existing context: inspect a revision and read a file.
New context: upload a prompt or skill to staging.
Ready for production: request a reviewed release.

Installation, human approval, workspace access, and successful reads are separate checks. Report which one succeeded.