Skip to content
GEOstack

AI setup · one paste

Set up Arc with your AI agent.

Paste one prompt into Claude Code or Codex and the agent does the rest: install @geostack/arc, set the two environment variables, wrap your project's highest-risk action in an allow / ask / block guard, and run one verified invocation end to end. You stay in the loop for exactly one thing — approving the action that needs a human.

The prompt

Copy everything in the block below and paste it as one message to your agent. Replace the token placeholder when the agent asks for it (or hand it the value out-of-band via your env file). If you self-host Arc, swap ARC_API_URL for your own URL.

paste into your agentprompt
You are setting up Arc (https://geostack.xyz) in this project. Arc is a trust layer that guards high-risk AI-agent actions with allow/ask/block policies, human approvals, signed execution, and an audit trail. Follow these steps in order and verify each one before moving on.

Prerequisites I must provide (stop and ask me if either is missing):
- An Arc workspace: https://app.geostack.xyz/sign-up
- An agent token, created in the Arc console under Agents (https://app.geostack.xyz/agents). It looks like arc_agent_...

Step 1 - Install the Arc SDK and CLI in this project:
  npm install @geostack/arc

Step 2 - Configure the environment (use my self-hosted Arc URL instead if I gave you one):
  ARC_API_URL=https://app.geostack.xyz/api
  ARC_AGENT_TOKEN=<the arc_agent_... token I created in the console>
Store both in this project's untracked env file (for example .env). Never print, log, or commit the token.

Step 3 - Verify connectivity and identity. Both commands must exit 0:
  npx arc dev smoke --json
  npx arc agent whoami --json
If either fails with HTTP 401, the token is wrong or revoked: stop and ask me to mint a new one in the console under Agents.

Step 4 - Guard this project's highest-risk action. Pick the one action with the largest blast radius (moves money, deletes data, sends external messages, or changes permissions) and route it through Arc, following https://geostack.xyz/docs/quickstart:
- Define the action with arc.defineActions, including a risk level and a defaultDecision of allow, ask, or block.
- Call it through createArcAgentRuntime({ apiUrl: process.env.ARC_API_URL, agentToken: process.env.ARC_AGENT_TOKEN }).invoke(appId, actionKey, input).
- Branch on result.status: "executed"/"queued" (allowed), "pending_approval" (a human must approve), "blocked" (refused - never work around a block).

Step 5 - Run one guarded action end to end with the CLI:
  npx arc agent apps --json
  npx arc agent actions --app <app-id-or-slug> --json
  npx arc agent invoke --app <app-id-or-slug> --action <action-key> --input '{"example":"value"}' --json

Step 6 - If the invoke result has decision "ask" (status "pending_approval"): tell me to approve it at https://app.geostack.xyz/approvals, then wait for my confirmation. Do not retry the action while it is pending.

Step 7 - Verify and report. Confirm the invocation executed (or was approved and then executed) and report back: the action key, the decision (allow/ask/block), the invocation id, and the approval id if one was created. Those ids are the audit evidence for this run.

Prefer the terminal? The CLI prints the same prompt (and keeps it current with your installed version): npx arc setup-prompt — or npx arc setup-prompt --json for {"prompt":"..."}. Self-hosted: npx arc setup-prompt --api-url https://arc.your-host.example.

What the agent will do

  1. 01 Install the SDK + CLI. Run npm install @geostack/arc in your project.
  2. 02 Configure the two env vars. Set ARC_API_URL to https://app.geostack.xyz/api and ARC_AGENT_TOKEN to the token you minted in the console, in an untracked env file.
  3. 03 Verify connectivity. Run arc dev smoke --json and arc agent whoami --json; both must exit 0.
  4. 04 Guard the riskiest action. Define the action with arc.defineActions and route the call through createArcAgentRuntime().invoke().
  5. 05 Run one guarded action. Invoke the action through the CLI and branch on the returned status.
  6. 06 Pause for human approval. If the decision is ask, approve it at https://app.geostack.xyz/approvals while the agent waits.
  7. 07 Verify and report. Confirm execution and report the decision, invocation id, and approval id.

Every CLI call the agent makes uses --json: exactly one JSON object or array on stdout, errors on stderr as {"error":{"code","message"}}, and exit codes the agent can branch on (0 success, 1 user error, 2 transport/server error).

The two environment variables

  • where arc lives ARC_API_URL The Arc API base. Hosted: https://app.geostack.xyz/api. Self-hosted: your own deployment URL. Overrides any saved CLI config.
  • who the agent is ARC_AGENT_TOKEN The agent's identity, minted by you in the console under Agents. Revoke it there at any time to cut the agent off instantly.
shell 
export ARC_API_URL="https://app.geostack.xyz/api"
export ARC_AGENT_TOKEN="arc_agent_..."   # console -> Agents. Keep out of git.

Troubleshooting

Next steps