Connect an agent to Steepworks.

Transports

Every transport authenticates as a real user. Each request resolves the user, their current Account membership, explicit scopes and, for project work, their current Project role. Domain applications use a separate machine credential and never act as a member.

CLI quick start

The CLI is a single Python file using only the standard library, so it can be copied onto any host without a package install. Put bin/steepworks on your PATH, then sign in:

steepworks auth login

This starts a ten-minute device request and opens a verification page in your browser. Confirm that the eight-character codes match. The credential binds to the browser's current Account and expires after 90 days.

Default login grants read and question scopes. Ask for more explicitly:

steepworks auth login --workspace-write      # edit tasks, report runs
steepworks auth login --knowledge-read       # read Knowledge pages
steepworks auth login --knowledge-write      # save and propose page edits
steepworks auth login --read-only            # status-only credential

Keep identities separate with profiles:

steepworks profile create ops
steepworks auth login --profile ops
steepworks profile set-project PROJECT --profile ops
steepworks profile set-default ops
steepworks profile list

Then discover and run commands. Arguments live in ordinary JSON files:

steepworks commands --agent
steepworks do tasks.list --in PROJECT --data empty.json --agent
steepworks do projects.create --data project.json --idempotency-key project-start-001 --agent

empty.json contains {}. project.json contains name and goal. --agent returns machine-readable output.

Scopes

questions:write and workspace:write require projects:read. knowledge:write requires knowledge:read. Commands that span Knowledge and project work need both read scopes; page-plan writes need all four. A scope on the credential is necessary but never sufficient: current membership, Project role and work authority are checked on every request.

Workspace commands

One catalog covers project creation and context, people, tasks, milestones, plans, progress reports, documents, money, native jobs and external run reports. The same business contexts serve the web UI, so what an agent can do is exactly what a member with the same role can do.

• Discover with steepworks commands --agent, the steepworks_workspace_commands MCP tool, or GET /api/v1/commands.
• Execute with steepworks do COMMAND, the steepworks_workspace_command MCP tool with {command, arguments, idempotency_key}, or POST /api/v1/workspace/commands/:command with the arguments as the body.

Rules every mutation follows

• Idempotency key. 8–200 characters, supplied by you (HTTP header Idempotency-Key). Reuse the exact arguments and key after a timeout to get the original receipt. A different body under the same key is a conflict.
• Observed version. Task edits and run updates require the lock_version you read. A stale edit is rejected so it can be reviewed against current work.
• Receipts. Durable per account and user, shared across transports.
• No implied authority. Plan application creates proposed tasks. It cannot import shipped status or customer acceptance. Changed plan inputs require another preview.

Preview and apply a plan from a reviewed definition:

steepworks do plans.preview --in PROJECT --data plan.json --agent
steepworks do plans.apply --in PROJECT --data reviewed-plan.json --idempotency-key plan-apply-001 --agent

reviewed-plan.json adds the digest returned by the preview and a stable source_key.

From milestone to verified pull request

Your coding agent writes the code. Steepworks plans the work, hands it off, checks what comes back and keeps the record. The project's Map tab lists each step and links to whatever is still missing.

1. Connect GitHub. An account admin installs the Steepworks GitHub App from Project settings, under Connections. It reads commits, pull requests and checks on the repositories you choose, and writes only to post the Steepworks check and, if you use a cloud agent, the hand-off issue.
2. Watch a repository and choose where coding happens. Choose a local agent through Ropetow, your own cloud agent started from a GitHub issue, or Steepworks builders. Your agents run on your own accounts and keys.
3. Plan a milestone with acceptance criteria and give each task one accountable owner. Accounts on Steepworks credits need credits available.
4. Hand off a work order from the task. It fixes the instructions, the acceptance criteria and a branch name, and it expires if no pull request answers it.
5. Open a pull request that quotes the task key (for example RC-12) in its title, body or branch. Steepworks checks it against the criteria and CI and posts a check named Steepworks. The check is evidence, not acceptance: a named person accepts the work.
6. Read the Map. It shows credits by milestone and step, your agents' runs (shown, never charged), review markers, work outside the plan, and estimates against actuals.

Linear, Notion and Jira

Once an admin connects a tracker, paste item links or keys into a milestone on the Map to make them tasks. Work orders, pull requests, finished runs, check results and acceptance are posted back to each item as comments. Steepworks never changes an item's status or fields. Each tracker is listed as available only after it has been verified end to end.

When something stalls

• The check did not appear on GitHub: give the App "Checks: write", then choose Retry verification on the task.
• "Model review did not run": fund credits or give the task an owner, then retry.
• The work order expired: hand the task off again when it is ready.
• A connection says reconnect: an admin reconnects it under Connections. Your project work stays available meanwhile.

Work from a coding agent

This is the loop that puts a run on the build map. Steepworks records the work; it does not start a process on anyone's computer.

1. Read the project and relevant documents. Use people.list to find assignees and tasks.context for a task's instructions and bounded source excerpts.
2. Create or select a task. Call runs.start with task, provider and your external session or job reference.
3. Execute in your coding tool.
4. Call runs.update with the returned run ID and lock version, the reported status, a summary and HTTP(S) evidence links.
5. Read runs.show or runs.list for the latest state. Task drawers in the cloud workspace show the same records.

Completed, failed and canceled runs are terminal; a new execution uses a new external reference. Reports are attributed observations, not proof that a provider or customer confirmed the result. Delivery review and acceptance follow their own rules.

jobs.run invokes installed planning and orchestration agents through the admission, budget and reviewer policy; read receipts with jobs.list.

MCP

Remote, stateless Streamable HTTP:

POST https://api.steepworks.com/api/v1/mcp

The server negotiates protocol 2025-11-25 and retains 2025-03-26 compatibility. After initialization, send the negotiated MCP-Protocol-Version header on every call; a missing header is treated as 2025-03-26 and an unsupported version fails with HTTP 400. Each JSON-RPC message is a separate authenticated POST. Responses are JSON; the server opens no event stream, so GET /api/v1/mcp returns 405.

Local stdio for agents on the same host:

steepworks mcp serve

Tools

Each named tool runs one catalog command with that command's schema, scope, observed versions and receipts. Writes take an idempotency_key. Every tool declares a title and read-only, destructive, idempotent and open-world hints.

Non-browser clients normally omit Origin. If one is sent, it must exactly match a trusted HTTPS origin; HTTP is accepted only for localhost development.

Remote OAuth

Deployments can accept RS256 JWT access tokens from a configured issuer. Steepworks publishes RFC 9728 metadata at /.well-known/oauth-protected-resource, challenges unauthenticated requests with WWW-Authenticate, returns an insufficient_scope challenge when a tool needs step-up, and verifies signature, issuer, exact audience, expiry and scopes on every request. Steepworks is not an authorization server; the issuer owns login, consent and token issuance. Remote OAuth is disabled until the deployment configures an issuer.

REST

Base URL https://api.steepworks.com/api/v1, bearer-authenticated as a user.

A separate, read-only Application API lets a connected domain application read its work projection and file bounded requests with a machine credential. It is provisioned by an Account admin and is not covered here.

Knowledge pages

pages.* commands work without a selected Project. Read the exact current source of a page and export it as Markdown:

steepworks do pages.read --data read-page.json --markdown > page.md

read-page.json contains {"page_id":"PAGE_UUID"}; add version_id for a specific immutable version. pages.save takes page_id, expected_version_id, lock_version, source_markdown and an optional title. pages.propose takes page_id, expected_version_id and source_markdown.

Accepted pages require a proposal. A person reviews and applies it from Proposed edits on the page; applying updates working content without replacing the accepted version. tasks.save changes a task body against its observed lock version without changing status or acceptance.

Page-driven planning: pages.plan.prepare with the page's expected_version_id, then pages.plan.update or pages.plan.suggest, then pages.plan.read and pages.plan.apply with its exact digest and lock_version. Prepare and update never create work; apply creates proposed work and preserves source links.

Codex and Claude Code plugins

One plugin serves both agents: the same skill and the same stdio MCP server. Sign in first, then install it from a Steepworks checkout:

steepworks auth login --workspace-write --knowledge-read
steepworks setup codex
steepworks setup claude

setup codex validates and copies the bundled plugin into your personal plugin directory, registers the steepworks marketplace entry, and runs codex plugin add. It refuses to replace an unmanaged destination. setup claude adds the steepworks marketplace to Claude Code and installs steepworks@steepworks. Start a new task afterwards so the skill and MCP server load. Goose connects over the same stdio MCP server.

Credentials and security

• Device codes carry 256 bits of random secret, are stored only as a SHA-256 digest, can be exchanged once, are rate-limited by a keyed network fingerprint, and never receive the browser session or password.
• User credentials expire after 90 days and are stored in the CLI config with owner-only file permissions. Profile listings never print them.
• Members inspect and revoke their own credentials at /app/settings/agent-connections. Account and Project membership changes take effect on the next request.
• Project coding connections use a separate restricted actor for approved execution attempts; they never inherit a member's credential.
• Supply bearer tokens through the environment, never on the command line: STEEPWORKS_TOKEN="$TOKEN" steepworks smoke agent-access --base-url https://api.steepworks.com --in PROJECT