---
title: "Docs — the Gruntas agent, CLI and upload API"
canonical_url: "https://gruntas.com/docs"
last_updated: "2026-11-22T12:53:15.733Z"
meta:
  description: "Install Gruntas and open its agent, push screenshots, recordings and HTML pages from AI agents like Claude Code and Cursor, and get links that render as cards in GitHub, Slack, Basecamp and Linear. Full command reference and the raw upload API."
  "og:description": "Install Gruntas and open its agent, push screenshots, recordings and HTML pages from AI agents like Claude Code and Cursor, and get links that render as cards in GitHub, Slack, Basecamp and Linear. Full command reference and the raw upload API."
  "og:title": "Docs — the Gruntas agent, CLI and upload API"
---

**Docs**

# **The CLI and the API, on one page. **

Installing Gruntas and opening its agent, then everything an agent, or the person wiring one up, needs to push a file and get back a link that renders as a card. Gruntas is MIT, at [~~github.com/krowkcom/krowk~~](https://github.com/krowkcom/krowk).

## Install

One script puts the CLI on the path:

terminal

```
$ curl -fsSL https://gruntas.com/install | bash
```

Or skip installing anything: `npx @krowk/cli` runs the same binary, and Rust users can `cargo install --locked --git https://github.com/krowkcom/krowk --features harness krowk`. It is one static binary with no runtime. On a workstation the script installs the full build, with the agent; in CI and containers it installs the lean build, which only publishes, because agent containers rarely have Node and the upload step should never fail for boring reasons. `--full` or `--lean` chooses (`curl … | bash -s -- --full`).

### The lean build

The lean build only publishes: no agent and no session store. It is what the installer picks in CI and in containers, and what `--lean` asks for; `--full` brings the agent.

## Open the agent

Sign in to what you already pay for — the Claude or ChatGPT subscription, SuperGrok — or add an API key, then open the agent in a repository. `krowk -p "…"` runs one prompt headless; `krowk --resume` picks a session back up.

terminal

```
$ krowk connect
$ krowk
```

The agent reads your Claude Code permissions, `AGENTS.md`, `CLAUDE.md`, skills and hooks as they are, and publishes with its own `publish` tool — the rest of this page is for publishing from any other agent. The full reference is the [~~README~~](https://github.com/krowkcom/krowk).

## Worktrees

Agents running at once can each work in a git worktree of their own, on a branch `krowk/<hex>`, so they don't overwrite each other's files.

- **Subagents.** `isolation: "worktree"` on the `subagent` call, or `isolation: worktree` in an agent definition's frontmatter, runs the child in a new worktree started from your files as they are, uncommitted changes included. When it finishes, an unchanged worktree is removed; a changed one is applied back to your working tree (never your index or HEAD) and removed. A conflict, a submodule change or a change to `.git`, `.claude`, `.codex` or `.krowk` keeps it, and the summary names it.
- **A session of its own.** `krowk --worktree` (or `krowk -p --worktree`) starts the session in a new worktree. On exit an unchanged one is removed and a kept one is named.
- **By default.**`"worktrees": { "default": true }`, in your config or a trusted repository's `.krowk/config.json`, starts every new session in a repository that way, whatever model or agent runs it. A worktree it can't make stops the session rather than letting it run in your checkout; `--worktree=false` runs one in place. The session runs in krowk's own process rather than the background host, so it ends with the terminal, and `/new` carries on in the same worktree.
- **No hand-made ones.** Whatever the backend or mode, an agent's `git worktree add`, or Claude Code's `EnterWorktree` and `Agent` with `isolation: "worktree"`, is refused and pointed to `krowk worktrees add`. So is an upload to a paste site ( `gh gist create`, `curl -F` to 0x0.st, transfer.sh and the like), pointed to `publish`. You can still run any of these at your own prompt.
- **Ready to build.** Submodules are initialised from your checkout, `target` and `node_modules` are cloned in where the file system makes that nearly free ( `worktrees.seed`), the ignored files your `.worktreeinclude` lists ( `.env`, local config) are copied, and `worktrees.setup` runs a command such as `npm ci` in the sandbox. A repository's own setup command runs only once you trust it. On btrfs a worktree is a snapshot, made in tens of milliseconds whatever the repository's size.
- **The machine's limits.** Build and test commands ( `cargo`, `make`, `npm`, `pytest`, …) from every krowk on the machine queue for `builds.slots` slots, a quarter of the cores by default. Subagents and `--worktree` sessions share `subagents.maxHost` agent slots. A worktree is refused when its disk is short of 4 GiB beyond twice its expected size.

| Command | What it does |
| --- | --- |
| `krowk worktrees` | List krowk's worktrees: base, commits ahead, uncommitted changes, whose session |
| `krowk worktrees add [--from <ref>]` | Make one for an agent on Claude Code or Codex to work in, and print its directory. It's outside the session's working directory, so its commands there may ask for approval. It stays until applied or removed |
| `krowk worktrees apply <hex> [--to <dir>]` | Bring a kept worktree's changes into your checkout, uncommitted |
| `krowk worktrees remove <hex> [--force]` | Remove one; `--force` saves its changes as a ref first, and the branch is kept |
| `krowk worktrees prune` | Clear what deleted worktrees left, and snapshots over 30 days old (also runs daily) |

```
{ "worktrees": { "setup": "npm ci" }, "builds": { "slots": 4 }, "subagents": { "maxHost": 16 } }
```

## Sessions

The full build keeps a local store of your agent sessions, whether they came from krowk, Claude Code, Cursor or opencode. `krowk sessions` lists them, newest first, and `krowk sessions show <id>` reads one back turn by turn. Sessions sync between your machines end-to-end encrypted: neither krowk's servers nor its relay can read them.

## Machines

`krowk machines` lists your machines: online or not, load per core, free memory, build and agent slots in use, and whether each accepts tasks handed over by your other machines. Inside a clone it says, for each other machine, `ready` or the one fix it needs. `krowk machines add` shows a QR code for the phone app; `always-on` and `recovery` keep a machine available and its recovery kit safe. Piped, it prints JSON.

## MCP servers

krowk's own agent uses the MCP servers you already set up for Claude Code: `mcpServers` in `~/.claude.json` (user and per-project) and in Claude's `settings.json`, plus `mcpServers` in `~/.krowk/config.json`. A repository's `.mcp.json` is used only after you trust the repository, and your own servers of the same name win over it. Each server takes Claude Code's shape, with `${VAR}` and `${VAR:-default}` expanded:

```
{
  "mcpServers": {
    "github": { "command": "github-mcp-server", "args": ["stdio"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } },
    "docs":   { "type": "http", "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" } }
  }
}
```

| Key | Purpose |
| --- | --- |
| `command`, `args`, `env` | A stdio server: the program krowk starts, and its arguments and environment |
| `type: "http"`, `url`, `headers` | A streamable-HTTP server |

`krowk mcp` manages the servers in `~/.krowk/config.json` without editing it by hand:

| Command | Does |
| --- | --- |
| `krowk mcp add <name> <url> [--header "Name: value"]` | Adds a remote server; `${VAR}` in a header keeps a token out of the file |
| `krowk mcp add <name> [--env K=V] -- <command> [args…]` | Adds a local (stdio) server |
| `krowk mcp login <name> [--no-browser]` | Signs in to a server that asks for OAuth |
| `krowk mcp logout <name>` | Forgets the sign-in |
| `krowk mcp list [--json]` | Lists every server krowk would load here, with where it comes from and whether you are signed in, without connecting |
| `krowk mcp remove <name>` | Removes a server from `config.json`, and its sign-in |

`add` refuses a name already in `config.json` unless you pass `--force`. Servers in a repository's `.mcp.json` or Claude Code's files are edited there; `remove` only touches `config.json`.

### Signing in to a server that asks for OAuth

Mobbin takes two commands:

```
krowk mcp add mobbin https://api.mobbin.com/mcp
krowk mcp login mobbin
```

`login` registers krowk with the server, opens your browser, and stores the tokens in the `mcp` section of `~/.krowk/credentials.json` (`0600`). Over SSH, or with `--no-browser`, it prints the sign-in page and waits for you to paste the address your browser lands on. krowk refreshes the tokens itself; if a refresh fails, a call to that server says "mobbin needs sign-in: run `krowk mcp login mobbin` or open /mcp". krowk never opens a browser in the middle of a turn. After that, ask krowk's agent for screens: it finds `search_screens` with `mcp_search`, and the images the server returns reach the model.

Servers stay connected for the life of a session. They restart only when their configuration or the repository's trust changes, after a failure, or on reconnect. In the TUI, `/mcp` lists each server with where it is configured, its status and its tool count; open one to see its tools, and sign in, sign out or reconnect from there. It does not enable or disable servers, since that would edit files krowk does not own. On a Claude Code backend your servers are reached through krowk's own `mcp_search` and `mcp_call` tools (Claude Code itself loads only krowk's tools), judged by krowk's `Mcp(...)` rules; the Codex backend does not get them.

The model sees two tools, `mcp_search` and `mcp_call`, however many MCP tools there are, so they cost no context until one is used. No server starts until the first search. Permission rules name a tool as `Mcp(server:tool)` or `mcp__server__tool`, and `Mcp(server)` names all of a server's tools; a server denied whole is never started.

## Configuration

Everything krowk keeps is in `~/.krowk/` (move it with `KROWK_HOME`): settings in `config.json`, keys in `credentials.json`, and sessions in `sessions/`. A repository can commit `.krowk/config.json` to pin a workspace or add permission rules. `krowk config` reads and sets values.

| Variable | Purpose |
| --- | --- |
| `KROWK_TOKEN` | API token (takes precedence over stored credentials) |
| `KROWK_WORKSPACE` | Which stored workspace key to use |
| `KROWK_API_URL` | Point at a self-hosted registry |
| `KROWK_NO_UPDATE_CHECK` | `1` disables release checks |

## First push, no account

agent shell

```
$ npx @krowk/cli push screenshot.png

✓ uploaded  screenshot.png  412 KB
  https://gruntas.com/a/art_00000000000000000000demo
  expires in 24h
  keep it:  krowk claim art_00000000000000000000demo krowk_claim_...
```

A keyless push lands in the anonymous workspace: the link works immediately and expires 24 hours later. The result also carries a **one-shot claim token** (`krowk_claim_…`). It is shown once and never again, so an agent that wants the link kept should surface it. One file is one artifact is one link; pushing three files creates three artifacts with three URLs.

## Keeping a link

Links in a claimed workspace do not expire. To move an anonymous upload into one:

1. [Create a workspace](https://app.gruntas.com/registration/new) at app.gruntas.com and generate an API key ( `krowk_sk_…`) in the dashboard.
2. Log the CLI in. The key is verified against the registry before it is stored:terminal

   ```
   $ krowk auth login --token krowk_sk_...
   ```


3. Spend the claim token the push printed:terminal

   ```
   $ krowk claim art_00000000000000000000demo krowk_claim_...
   ```



Claiming works for 30 days after a link expires, and the URL comes back exactly as it was. With a key configured, every push lands in your workspace directly and there is nothing to claim.

## Commands

| Command | What it does |
| --- | --- |
| `krowk push <file...>` | Upload files, get a link for each |
| `krowk uploads create <file...>` | The same thing, spelled out |
| `krowk uploads list` | List the workspace's uploads, newest first (--limit, --before) |
| `krowk uploads show <artifact>` | Read one artifact back |
| `krowk uploads attach <artifact> --run <run>` | Put an upload under a run after it was uploaded |
| `krowk runs start` | Open a run to group later uploads under |
| `krowk runs finish <run>` | Close a run |
| `krowk claim <artifact> <claim-token>` | Keep an anonymous upload past its expiry (--run groups it while claiming) |
| `krowk auth login --token <token>` | Verify a key against the registry, then store it in \~/.config/krowk/credentials.json |
| `krowk auth token` | Print the stored token, for scripts |
| `krowk auth verify` | Ask the registry which key this is, and the workspace it acts in |
| `krowk doctor` | Report version, API reachability, auth and detected run context |

Upload flags: `--run`, `--pull-request`, `--reference` (repeatable), `--session`, `--title`, plus `--repo`, `--commit` and `--agent` to override what the CLI detects from the environment. Global flags: `--format human|json|markdown|url`, `--json`, `--quiet`, `--dev`. Output is human on a TTY and JSON when piped, so an agent that captures stdout gets structured data without asking for it.

## Pasting the result

There is no single paste-ready string, because the destinations disagree about what they render:

| Destination | Use | Why |
| --- | --- | --- |
| GitHub, Linear, Notion | `--format markdown` | They build preview cards only for their own resources. The inline image embed is what actually renders the artifact in a PR comment. |
| Slack, Basecamp | `--format url` | Both unfurl a bare URL into a card of their own. Slack renders no markdown image embeds at all. |

`--json` carries both forms under `paste`, one line per artifact, with link labels escaped for CommonMark so a filename like `frame[0].png` pastes as a working link.

## Runs: where the metadata lives

An artifact is just the file. The repo, commit, branch, agent, pull request and session live on a **run**, and artifacts attach to it. With a key, every push not given `--run` opens and closes its own run; `krowk runs start` opens one to group a whole session under. Keyless uploads have no run: metadata named by flag is not recorded, and the result says so rather than dropping it silently.

## The API, with curl

The CLI speaks a documented REST API at `api.gruntas.com/v1`, so you can upload with nothing installed. Bytes never pass through the registry. An upload is three steps:

1. **Declare.** `POST /v1/artifacts` with the filename, content type, byte size and hex-encoded SHA-256 checksum. The response carries the artifact's slug and a presigned `upload.url` with the exact headers to send. Size and digest are declared up front because they are signed into the URL, which is how storage refuses an oversized or corrupted body at the edge.
2. **Upload.** `PUT` the bytes straight to that URL.
3. **Finalize.**`PUT /v1/artifacts/:slug/finalization` confirms what landed. Idempotent: a retry gets the same success.

terminal

```
$ curl -s https://api.gruntas.com/v1/artifacts \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "screenshot.png",
    "content_type": "image/png",
    "byte_size": 421888,
    "checksum": "<hex sha-256 of the file>"
  }'
```

Authenticate with `Authorization: Bearer krowk_sk_…` to land the artifact in your workspace; without it the upload is anonymous and the declare response includes the claim token. Every failure has one shape, `{ "error": { "code", "message", "details" } }`, with a machine-readable code and the actual offending value, so a client (or an LLM) can act on it without parsing prose.

## Limits

|  | Free | Pro | Business |
| --- | --- | --- | --- |
| Link lifetime | 24 hours | Never expires | Never expires |
| Uploads | 100 a day | 10,000 a month included | 30,000 a month included |
| Artifact size | 100 MB | 2 GB | 2 GB |
| Storage | — | 100 GB included | 100 GB included |
| Recovery window | 30 days after expiry | — | — |
| Visibility | Public | Public | Private and shared |

Nothing bills past the included amounts; prices are on the [pricing page](https://gruntas.com/pricing). Every key, and every address pushing without one, has a per-minute ceiling on new uploads, on by default and not switchable off: past it the API answers `429` with `Retry-After`, and nothing new lands until you wait the seconds it names.

## Development

```
make check   # clippy, unit tests and golden tests
make dev     # fast build, linked into ~/.cargo/bin
make mock    # local registry; run any command with --dev
```

[~~The changelog~~](https://github.com/krowkcom/krowk/blob/main/CHANGELOG.md) lists what changed in each release, and the [~~krowk-bench README~~](https://github.com/krowkcom/krowk/tree/main/crates/krowk-bench) has the performance and size budgets.

## Where to go next

This page is the reference. For the same material as a walkthrough — getting a screenshot from an agent into a pull request, or out of a CI run — see [the guides](https://gruntas.com/guides). For why the card carries a commit at all, there is [how it works](https://gruntas.com/how-it-works) and [the argument for provenance](https://gruntas.com/blog/agent-output-provenance). The refusals the CLI and the MCP server make, with the reasoning, are on [the security page](https://gruntas.com/security).