Namespace

The namespace integration lets agents drive Namespace ephemeral compute: create an instance, run containers inside it, extend or suspend it, and destroy it when done. Every action is a server-side call to the regional Compute API with a Bearer token you mint once; the token never leaves the server.

This first slice covers instances. Runner profiles, vault objects, remote builders, artifacts, volumes, registry, reservations, and revokable tokens follow in later slices and reuse the same credential.

Prerequisites

• A Namespace workspace and the nsc CLI installed (brew install namespacelabs/namespace/nsc, or see Installation).
• Permission to create revokable tokens in that workspace.

Mint a revokable token

nsc login
nsc token create \
  --name popcornteam \
  --description "PopcornTeam agents" \
  --expires_in 720h \
  --grant '{"resource_type":"instance","resource_id":"*","actions":["create","get","list","destroy","exec","refresh","suspend","resume"]}'

nsc token create prints the token once. Copy it straight into PopcornTeam; do not store it in a repository. Trim the actions list to the actions you actually enable for the agent.

Use one token per PopcornTeam workspace. Rotate by minting a new token, updating the credential in PopcornTeam, then running nsc token revoke on the old one.

Grants (least privilege)

Each action needs one grant on the instance resource. The Namespace permissions reference lists every resource and action; this slice uses:

A token without instance:list still connects; PopcornTeam treats a 403 on the connection probe as "authenticated, not yet granted" and reports the missing grant on the action that needs it.

Connect

1. In PopcornTeam, go to /agents/integrations and find Namespace.
2. Paste the token into Token.
3. Optionally set Region (default us). It becomes the API host: https://<region>.compute.namespaceapis.com.
4. Save. PopcornTeam probes ListInstances with maxEntries: 1 to confirm the token is accepted.

Actions

All actions return the raw Compute API response as JSON.

• Create — virtualCpu (default 2), memoryMegabytes (default 4096), machineArch (amd64 | arm64), documentedPurpose, deadlineMinutes (default 60), interactive, labels (JSON object, e.g. {"repo":"owner/name"}), containers (JSON array of {name, imageRef, args, environment}).
• Get / List — describe one instance, or page through instances with maxEntries, includeCompleteRuns, and paginationCursor.
• Extend — extendByMinutes pushes the deadline out; ensureMinimumMinutes only tops it up to at least that much remaining time.
• Suspend / Resume — pause a running instance and wake it later.
• Run containers — start additional containers in a running instance.
• Destroy — tear the instance down immediately, with an optional reason.

Label every instance with the repository it serves ({"repo":"owner/name"}) so namespace_list_instances output can be filtered per repo.

Vault convention (per repository)

Keep repository secrets in the Namespace workspace vault, one labeled object per .env.local file:

labels: repo=<owner>/<name>, file=<path-to-env-file>

For example, repo=acme/app, file=apps/admin/.env.local. Vault actions land in a later slice; label objects this way now so the agent can resolve them without a lookup table.

Troubleshooting

• Invalid Namespace API token — the token was revoked, expired, or pasted with whitespace. Mint a new one.
• permission_denied on an action — add the grant from the table above to the token.
• Invalid region — regions are lowercase letters, digits, and hyphens (e.g. us, eu).
• Instance disappears — instances are destroyed at their deadline. Extend before it passes, or create with a longer deadlineMinutes.