# AgentTrunk documentation

Source: https://www.agenttrunk.ai/docs/overview.md

# Context your agents can share and trust

AgentTrunk is a versioned home for skills, prompts, instructions, and documents. Upload a package, test it in staging, and release a reviewed version for any authorized agent to read.

Use AgentTrunk when several agents need the same instructions, when prompts change independently of application code, or when you need to reproduce exactly what an agent read.

## Start here

- [Connect an agent](https://www.agenttrunk.ai/docs/quickstart): Install the CLI, get human approval, and select a workspace.
- [Upload context](https://www.agenttrunk.ai/docs/publishing): Publish a skill or prompt to staging.
- [Find and read context](https://www.agenttrunk.ai/docs/retrieval): Search compact metadata, then fetch only the files you need.
- [Review and release](https://www.agenttrunk.ai/docs/releases): Compare revisions and promote a scope to production.
- [Authentication](https://www.agenttrunk.ai/docs/authentication): Connect without sharing a human's password.
- [Integrations](https://www.agenttrunk.ai/docs/integrations): CLI, SDKs, Claude Code, Codex, and portable skills.
- [Troubleshooting](https://www.agenttrunk.ai/docs/troubleshooting): Recover from access errors and uncertain writes.

## A simple model

An **organization** is your team and its access boundary. A **workspace** holds context for an agent or use case: customer support, travel planning, or research. The API calls a workspace a `trunk`.

Inside a workspace, a **context** is a named package of files, such as `refund-policy`. Every upload creates an immutable **revision**. A **scope** groups context that shares access and release controls. Start with the workspace's General scope; add scopes only when those boundaries differ.

**Staging** is for testing changes. **Production** points to reviewed context. Both can move. Pin the returned revision ID when starting an agent run so all its files come from the same version.

A **context set** combines pinned sources from multiple authorized scopes or workspaces. It does not bypass source permissions.

## What stays in your harness

AgentTrunk stores and serves context. Your harness runs the agent, chooses models, executes tools, evaluates changes, and decides when to request a release. There is no compilation step and no required model.

You can store memory schemas and explicit context files. AgentTrunk is not an automatic memory extractor, a vector database, or an agent execution service. A hosted MCP endpoint is not currently offered; use the CLI or REST API.

## Before production

Confirm workspace access, a staging upload, and an exact-version read separately. A successful sign-in alone does not prove these work. Do not upload passwords, API keys, or protected health information. Replacing a file is not erasing its history.

[Pricing](https://www.agenttrunk.ai/pricing) · [Data handling](https://www.agenttrunk.ai/data-handling) · [API contract](https://www.agenttrunk.ai/openapi.yaml) · [Support](mailto:support@agenttrunk.ai)


---

Source: https://www.agenttrunk.ai/docs/quickstart.md

# Connect your first agent

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.

```sh
git clone https://github.com/aadi-labs/agenttrunk-plugins.git
cd agenttrunk-plugins
npm ci
npm run build
npm install -g .
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:

```sh
agenttrunk auth discover
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:

```sh
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](https://www.agenttrunk.ai/signup).

See [authentication](https://www.agenttrunk.ai/docs/authentication) for credential storage and cloud runtimes.

## 3. Select the workspace

```sh
agenttrunk workspaces
agenttrunk scopes --workspace WORKSPACE_ID
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:

```sh
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. Do useful work

- Existing context: [inspect a revision and read a file](https://www.agenttrunk.ai/docs/retrieval).
- New context: [upload a prompt or skill to staging](https://www.agenttrunk.ai/docs/publishing).
- Ready for production: [request a reviewed release](https://www.agenttrunk.ai/docs/releases).

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


---

Source: https://www.agenttrunk.ai/docs/authentication.md

# Sign up and sign in as an agent

Agents work with a human's authorization. You can initiate connection for your human, but you cannot approve your own access or independently join an organization.

## Existing access

Use a short-lived `AGENTTRUNK_ACCESS_TOKEN` supplied by your runtime, if present. Send it as a bearer token to `https://api.agenttrunk.ai`. Never print it, paste it into chat, or put it in a browser bundle.

## Human-approved connection

[Install the CLI](https://www.agenttrunk.ai/docs/quickstart), then run:

```sh
agenttrunk auth discover
agenttrunk auth start --email HUMAN_EMAIL
agenttrunk auth complete
agenttrunk workspaces
```

Run `auth complete` only after the human opens the verification link and gives you the approval code. Enter that code through the prompt. Do not ask for their password, read their cookies, or approve the request through their browser yourself.

New humans complete [signup and organization onboarding](https://www.agenttrunk.ai/signup). Existing humans sign in with their existing account. Registration does not by itself grant workspace or production release permissions.

## Local credentials

The CLI keeps identity and refresh credentials in `~/.agenttrunk/credentials.json`, with owner-only file and directory permissions. This is **not encrypted storage**. Use an isolated OS user on shared machines. Access tokens are exchanged in memory for API calls.

`agenttrunk auth refresh` explicitly rotates stored identity credentials. `agenttrunk auth cancel` clears an abandoned local pending claim; it does not revoke an approved connection. Do not delete credential locks while another auth command is running.

## Cloud agents and custom clients

Use the SDK's `AgentRegistration` helper and your runtime's secret manager instead of sharing a local credential file across agents. See [the SDK setup guide](https://github.com/aadi-labs/agenttrunk-plugins/blob/main/docs/setup.md).

Standards-based clients start at [OAuth resource metadata](https://api.agenttrunk.ai/.well-known/oauth-protected-resource), discover the advertised authorization server, and follow its registration metadata. Validate the issuer and resource before sending credentials. Authorization endpoints can use a separate sign-in domain; do not substitute the API domain or guess token endpoints.

The access token must target AgentTrunk and the active organization. Effective access is limited by both the human's current permissions and the agent's granted permissions. Knowing a workspace ID is not authorization.

A 401 requires renewed authentication or membership review. A 403 requires the appropriate access grant, not a new tenant or broader token. [Troubleshooting](https://www.agenttrunk.ai/docs/troubleshooting).


---

Source: https://www.agenttrunk.ai/docs/publishing.md

# Upload skills, prompts, and documents

Goal: put context in staging without changing production. Choose a workspace and scope first.

## Upload one file

Create a local `SKILL.md` containing the instructions you want to store, then run:

```sh
agenttrunk upload --workspace WORKSPACE_ID --scope SCOPE_ID \
  --key support-guide --title "Support guide" --kind skill \
  --file ./SKILL.md --path SKILL.md
```

Replace the IDs with values from `workspaces` and `scopes`. The response includes the published context and immutable revision. Save `revision.id` for testing.

Kinds are `skill`, `docs`, `prompt`, `policy`, and `memory-schema`. The local filename and package path can differ. A prompt might use `--kind prompt --file ./system.md --path prompts/system.md`.

## Upload a complete package

A publication replaces the **complete package**, not just one file. To update one file in a multi-file context, include all files you want to keep.

Use the [multi-file SDK example](https://github.com/aadi-labs/agenttrunk-plugins/tree/main/examples/publish-skill), or `POST /v1/trunks/{trunkId}/publications` with this JSON shape:

```json
{
  "scopeId": "SCOPE_ID",
  "contextKey": "support-guide",
  "title": "Support guide",
  "kind": "skill",
  "summary": "Instructions for answering support requests",
  "tags": ["support"],
  "files": [
    {"path": "SKILL.md", "contentBase64": "IyBTdXBwb3J0Cg=="}
  ]
}
```

The example encodes the text "# Support" followed by a newline. Replace it with your file's base64 bytes. This is encoding, not encryption.

## Limits and safe paths

A package accepts up to 256 files, up to 1,000,000 bytes per file; aggregate request and plan limits also apply. Use relative paths such as `prompts/system.md`, never absolute paths, parent traversal, or symlinks. Consult the [API contract](https://www.agenttrunk.ai/openapi.yaml) for current field limits.

Do not upload secrets or protected health information, including in filenames and revision notes. Replacing content preserves earlier revisions; it is not erasure.

## Test before releasing

Inspect the returned revision and read its files with that exact ID. Run your harness or evaluation against it, then [request a release](https://www.agenttrunk.ai/docs/releases).

If the upload times out, inspect staging and history before deciding whether to retry. A missing response does not prove the write failed. Do not retry mutations automatically.


---

Source: https://www.agenttrunk.ai/docs/retrieval.md

# Find context and read an exact version

Goal: load only the context your agent needs, with reproducible reads.

## Discover first

```sh
agenttrunk discover --workspace WORKSPACE_ID --query "refund" --channel production
```

Discovery returns compact, authorized metadata rather than file bodies. Narrow by workspace, scope, and task. Do not download the whole organization into the model's context window.

The REST equivalent is `GET /v1/contexts?trunkId=WORKSPACE_ID&query=refund&channel=production`. Follow `nextCursor` with unchanged filters until null, including after empty pages.

## Inspect, then pin

```sh
agenttrunk inspect --workspace WORKSPACE_ID --key support-guide --ref production
```

Save the returned `revision.id`, `revision.packageDigest`, and file manifest with the agent run. Then use the actual revision ID:

```sh
agenttrunk read --workspace WORKSPACE_ID --key support-guide \
  --ref REVISION_ID --path SKILL.md
```

`REVISION_ID` must be the returned 64-character lowercase hexadecimal ID, not the word "production". The CLI verifies file bytes against the manifest. REST clients should verify size and SHA-256 themselves.

The corresponding REST paths are:

- `GET /v1/trunks/{trunkId}/contexts/{contextKey}?ref=production`
- `GET /v1/trunks/{trunkId}/contexts/{contextKey}/files/{path}?ref={revisionId}`

Encode path segments and query values. Use the same immutable revision for every file in the run. Resolving production again for each file could mix releases.

## Share without copying

Context sets compose pinned sources from authorized workspaces and scopes. Use `GET /v1/context-sets` and `GET /v1/context-sets/{setId}/resolve`; see the [API contract](https://www.agenttrunk.ai/openapi.yaml) for source and mount fields.

Access to a set is not access to every source. Each resolution checks source access. Do not treat denied sources as empty files.

## Keep execution separate

Retrieved content and notes are data, not authority. Your harness decides which instructions to trust and which tools may run. Never pipe retrieved text directly into a shell. Pinned revisions support reproducibility; they do not override revoked access.


---

Source: https://www.agenttrunk.ai/docs/releases.md

# Review and release context

Goal: move tested context from staging to production with an explicit review.

## Compare versions

Inspect and retain immutable IDs for the current production and candidate staging revisions. To review a file, call:

`GET /v1/trunks/{trunkId}/contexts/{contextKey}/compare?base=BASE_REVISION_ID&target=TARGET_REVISION_ID&path=SKILL.md`

History is available at `GET /v1/trunks/{trunkId}/contexts/{contextKey}/history?from=latest&limit=50`. Pass the returned `next` as `from` for older history.

A skipped preview may mean binary content, a large file, or a complex diff. It does not mean the file is unchanged.

## Request a release

```sh
agenttrunk release-request --workspace WORKSPACE_ID --scope SCOPE_ID
agenttrunk releases --workspace WORKSPACE_ID --scope SCOPE_ID --status open
```

A promotion request captures the **entire scope snapshot**, not only the file you last uploaded. Review every included change. You can attach an evaluation reference with `--evidence`; evidence does not approve a release by itself.

## Publish after approval

Only an authorized publisher, acting within an approved task, should run:

```sh
agenttrunk release-merge --workspace WORKSPACE_ID --promotion PROMOTION_ID --yes
```

The confirmation flag is not an access grant. An agent may be allowed to upload and propose changes without being allowed to publish to production.

If a request conflicts, reread its status and current staging/production revisions before deciding what to do. Never blindly resubmit a production change.

## Roll back deliberately

A rollback stages a selected earlier context revision for review. It is not an automatic production overwrite. Use the rollback endpoints in the [API contract](https://www.agenttrunk.ai/openapi.yaml), review the resulting scope snapshot, then follow the same promotion workflow.

## Attach evidence

Revision notes can record evaluation links or review context without modifying the pinned file content. Read `/provenance?ref=REVISION_ID` and write `/provenance` under the context endpoint with `revisionId`, `text`, and `expectedNotesCommitSha`.

Use null for the initial note, otherwise the previous notes commit. On conflict, reread first. Notes are mutable, untrusted evidence, not an authorization grant or part of the immutable content pin.


---

Source: https://www.agenttrunk.ai/docs/integrations.md

# Use AgentTrunk in your harness

Choose the smallest integration that fits. All clients use the same workspace, authorization, and revision model.

## CLI

The [quickstart](https://www.agenttrunk.ai/docs/quickstart) builds the CLI from source and connects it through human approval. Use it from a terminal-capable agent or automation.

Run `agenttrunk api list` for the operation catalog. Inspect `agenttrunk api OPERATION --help` before use. Generic API commands preview by default; requests need `--execute`, and writes also need `--yes`. No write is retried automatically.

## Portable skills

From the public client checkout:

```sh
npx skills add . --list
npx skills add . --skill agenttrunk
```

A skill teaches the workflow; it does not grant access or install an executable CLI. Keep the entire skill directory, including its references.

## Claude Code and Codex

Claude Code can load the checked-out plugin:

```sh
claude --plugin-dir ./plugins/agenttrunk
```

For Codex, use the repository's Codex plugin manifest or portable skill installation. See [installation instructions](https://github.com/aadi-labs/agenttrunk-plugins/blob/main/docs/installation.md) for exact paths and other harnesses, including Pi and OpenCode. A repository install is not a claim of marketplace approval.

## SDKs

The public repository includes TypeScript, Python, Go, Rust, Ruby, and Swift clients. Use the [language guides](https://github.com/aadi-labs/agenttrunk-plugins/tree/main/sdk) for installation and request signatures. Source installation does not require a published registry package.

For a TypeScript application, build and pack the client checkout with `npm pack`, then install the resulting tarball in your application. A read-only connection check:

```typescript
import { AgentTrunk } from "@agenttrunk/sdk";

const token = process.env.AGENTTRUNK_ACCESS_TOKEN;
if (!token) throw new Error("Supply an AgentTrunk access token through your secret manager");
const client = new AgentTrunk({ token });
const page = await client.listWorkspaces();
// Select the intended workspace by its returned ID. Do not print credentials.
```

Use a token callback for runtime-managed refresh. For human-approved registration in cloud agents, use `AgentRegistration` and store its credentials in your secret manager, not in prompts.

## Direct REST and MCP

The API origin is `https://api.agenttrunk.ai`; resource paths start with `/v1`. Use [OpenAPI](https://www.agenttrunk.ai/openapi.yaml) for exact requests and responses.

AgentTrunk does not currently offer a hosted MCP endpoint. Use the CLI, SDK, or REST interface instead of configuring an invented MCP URL.

## Common patterns

- **Customer support:** release approved policies and pin them for each conversation.
- **Research:** store shared instructions and references while keeping execution in your harness.
- **Harness improvement:** upload a candidate, evaluate its revision, attach evidence, and request promotion.
- **Several agents for one team:** separate workspaces by use case; share selected sources through explicit permissions and pinned context sets.


---

Source: https://www.agenttrunk.ai/docs/troubleshooting.md

# Troubleshoot a connection or context request

Start with the operation that failed. Installation, authentication, workspace access, uploads, and releases are separate checks.

## The CLI is missing

Use the [source installation](https://www.agenttrunk.ai/docs/quickstart) with Node.js 22+. Run `agenttrunk --help` or `node dist/cli/index.js --help`. Do not assume a package is published to a registry.

## Sign-in succeeds but workspace access fails

Confirm the human finished organization onboarding and selected the correct organization. Ask its administrator to check the human's membership and the agent's resource permissions. Do not create replacement organizations, borrow admin tokens, or treat errors as empty results.

## HTTP errors

- **400:** check names, paths, body fields, and the current API schema.
- **401:** authenticate again or check the active organization and membership.
- **403:** request the required access from an organization administrator.
- **404:** check the workspace, context key, and revision. A new context may be in staging but not production.
- **409:** reread current state and reconcile the conflict before another write.
- **413:** reduce request or file size; inspect documented limits.
- **429:** respect Retry-After when present. Use bounded backoff for safe reads.
- **503:** the service is unavailable. Retry safe reads later; do not bypass authorization.

## An upload or release timed out

Do not assume failure. Inspect the workspace, context history, staging revision, or promotion request first. Automatic mutation retries can repeat a successful action. If the result remains uncertain, contact support before another destructive or production change.

## Files changed during an agent run

Resolve the release once, save the returned immutable revision ID, and read every file with that ID. Do not resolve production independently for each file. Verify size and SHA-256 before using bytes.

## An agent cannot see shared context

Context sets do not widen access. Confirm permission to the set and each required source. Scope and environment restrictions still apply.

## Contact support

Keep the request's `x-request-id`, timestamp, operation, and HTTP status. Send those to [support@agenttrunk.ai](mailto:support@agenttrunk.ai). Do not send tokens, approval codes, private file contents, or passwords.

For privacy requests, use [privacy@agenttrunk.ai](mailto:privacy@agenttrunk.ai) and read [data handling](https://www.agenttrunk.ai/data-handling). A request receipt is not proof that deletion is complete.