Agent quickstart

Use this guide to connect a coding agent to StackMachine and add the SDK to an existing project. This environment uses https://api.stackmachine.dev/graphql. Use that same endpoint for login, credential verification, and SDK requests.

1. Authenticate

Read the agent authentication instructions. Reuse an existing valid credential when available. Otherwise, create a login claim and show the human the approval URL and public code. Wait 15 seconds before the first redemption poll, then poll every 5 seconds while pending (or at the returned interval if longer). The human must explicitly approve in the browser. Keep polling without asking them to reply once authorized, and continue automatically when the user access token is returned.

Save the redeemed personal token as STACKMACHINE_USER_ACCESS_TOKEN. List the user’s workspaces and ask which one to use, even if only one is available. If there are none, ask whether to create a workspace before creating it. A workspace in the UI is a namespace in GraphQL.

Prefer a workspace API token for integrations: after the human chooses a workspace and agrees to token creation, create or reuse its API token and save it as STACKMACHINE_API_TOKEN. This credential is scoped to that workspace. See Tokens for the personal user-token alternative.

Keep the private claim token and returned access token out of chat, browser URLs, source code, and logs. Store the access token in the project’s secret manager or an ignored local environment file with owner-only permissions. Workspace tokens can be revoked from the workspace’s API Keys page; personal user tokens from the dashboard’s Access Tokens page.

See Agent authentication for a summary of the claim flow and permissions.

2. Install the SDK

Use the package manager and language already used by the project:

install

npm install stackmachine

3. Configure the client

Set the server-side STACKMACHINE_API_TOKEN to the chosen workspace API token. Pass its value explicitly to new StackMachine(...); the SDK does not read the environment variable automatically. Keep this client in backend code or the agent’s tools so the token is never bundled into a browser application.

These examples explicitly select this environment’s API URL because it differs from the SDK default.

stackmachine.mjs

import StackMachine from "stackmachine";
 
const token = process.env.STACKMACHINE_API_TOKEN;
if (!token) throw new Error("STACKMACHINE_API_TOKEN is required");
 
const client = new StackMachine(token, { apiUrl: "https://api.stackmachine.dev/graphql" });

Before making changes, verify access with a read-only operation in the selected workspace. The viewer check in auth.md verifies a personal user token; do not require it to return a user for a workspace API token. If authentication fails, check that the token, workspace, and API endpoint match. Do not print the token while diagnosing a failure.

4. Integrate the resources your project needs

Reuse the configured client for the required SDK calls. Set deployment owner to the selected workspace’s name (the GraphQL namespace name). Deployment examples use placeholder owners that must be replaced with this name.

List apps: discover existing apps before creating another.
Deploy from files: create a deployment and wait for the resulting app URL.
Redeploy: update an existing app.
Cloud storage, databases, mail, and cron jobs: add the services requested by the project.

Keep the same API endpoint when adapting examples from other pages. Complete the requested integration, run the project’s checks, and report the result without sharing credentials.