---
title: "Agent quickstart"
description: "Authenticate your coding agent and integrate the StackMachine SDK into your project."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent quickstart

Use this guide to connect a coding agent to StackMachine and add the SDK to an
existing project. This environment uses <code>{getDocsApiUrl()}</code>.
Use that same endpoint for login, credential verification, and SDK requests.

## 1. Authenticate

Read <a href={siteUrl('/auth.md')}>the agent authentication instructions</a>.
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](/getting-started/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](/getting-started/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:

```bash
npm install stackmachine
```

```bash
pip 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.

<p>{getDocsApiUrl() === PRODUCTION_API_URL
  ? 'The SDK uses the production API by default, so no API URL option is needed.'
  : 'These examples explicitly select this environment’s API URL because it differs from the SDK default.'}</p>

```javascript
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);
```

```python
import os
from stackmachine import StackMachine

token = os.environ["STACKMACHINE_API_TOKEN"]
client = StackMachine(token)
```

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](/apps/list): discover existing apps before creating another.
- [Deploy from ZIP](/apps/deployments/from-zip): zip a project source folder, excluding
  dependencies and generated files. StackMachine automatically detects the project,
  installs dependencies, and builds it for you.
- [Deploy from files](/apps/deployments/from-files): deploy inline source files and wait
  for the resulting app URL.
- [Redeploy](/apps/deployments/redeploy): update an existing app.
- [Cloud storage](/volumes), [databases](/databases),
  [mail](/mails), and [cron jobs](/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.

Source: https://docs.stackmachine.com/agent-quickstart/index.mdx