# GPU compute your agent can use safely

Run commands from a local project on bounded remote GPUs while the agent and Git workflow stay local.

Canonical: https://docs.amics.ai/

<div className="docs-signal">
  <span>
    Local agent
  </span>

  <span aria-hidden="true">
    →
  </span>

  <span>
    Immutable source snapshot
  </span>

  <span aria-hidden="true">
    →
  </span>

  <span>
    Bounded GPU run
  </span>
</div>

Amics gives coding agents and developers the same provider-neutral command-line
interface to remote GPU compute. You approve a maximum price and runtime. Amics
snapshots the project, runs one literal command, streams its output, records the
result, and stops auto-acquired compute by default.

```bash
curl -fsSL https://downloads.amics.ai/cli/install.sh | sh
amics login
amics skill install
amics gpu options --min-vram 24 --max-runtime 30m

# Replace this placeholder with a family returned above, without spaces.
amics run \
  --gpu CHOSEN_GPU_IDENTIFIER --min-vram 24 \
  --max-hourly-price 1.50 --max-runtime 30m \
  -- nvidia-smi --query-gpu=name,memory.total --format=csv,noheader
```

## What you can do now [#what-you-can-do-now]

<Cards>
  <Card title="Run local projects" href="/cli/run">
    Execute training, evaluation, rendering, and batch commands on a remote GPU.
  </Card>

  <Card title="Delegate to an agent" href="/agents">
    Install the Amics skill so an agent follows the spend, secret, and lifecycle rules.
  </Card>

  <Card title="Reconnect to durable runs" href="/cli/runs">
    Follow logs, inspect an interrupted command, cancel it, or detach safely.
  </Card>
</Cards>

## The boundary [#the-boundary]

| Stays local                            | Goes to the remote run                                                |
| -------------------------------------- | --------------------------------------------------------------------- |
| Coding agent and chat history          | Selected project snapshot                                             |
| Git credentials and commits            | Literal command arguments                                             |
| Agent login and saved Amics credential | Environment values named with `--env`, including workload credentials |
| Source edits and experiment decisions  | Process stdout, stderr, and exit status                               |

Amics is not SSH, a remote desktop, a live filesystem mount, or a locally
attached CUDA device. It is bounded command execution with durable run state.

## Choose a path [#choose-a-path]

<Cards>
  <Card title="Five-minute quickstart" href="/getting-started/quickstart">
    Install, authenticate, check capacity, and run a first command.
  </Card>

  <Card title="Agent setup" href="/agents/install-skill">
    Give Codex, Claude Code, Cursor, or another compatible agent the Amics skill.
  </Card>

  <Card title="CLI overview" href="/reference/cli">
    See the command surface, output modes, and exit statuses.
  </Card>

  <Card title="HTTP API" href="/reference/endpoints">
    Integrate GPU options, snapshots, runs, and output directly.
  </Card>
</Cards>

## Documentation for agents [#documentation-for-agents]

Documentation pages are available as Markdown by appending `.md` to their URL
or requesting `Accept: text/markdown`. The homepage is [`/index.md`](/index.md).
Use [`/llms.txt`](/llms.txt) for the page index and [`/llms-full.txt`](/llms-full.txt)
for the complete corpus.

---

# Approval and safety

The spend, secret, replay, and cleanup rules an unattended agent must follow.

Canonical: https://docs.amics.ai/agents/approval-and-safety

## Read and write actions are different [#read-and-write-actions-are-different]

`amics gpu options` reads live capacity. It does not create a resource or choose
a GPU.
`amics run` may acquire paid compute. An agent must not infer approval for the
second action from a request for the first.

## Approve one acquisition envelope [#approve-one-acquisition-envelope]

Before an unattended acquisition, establish:

| Bound               | CLI option           | What it controls                                                                                            |
| ------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------- |
| Maximum hourly rate | `--max-hourly-price` | Compute and its attached runtime disk                                                                       |
| Command deadline    | `--max-runtime`      | How long the remote command may run                                                                         |
| Warm reuse window   | `--keep-warm`        | How long compatible compute may remain after the command; billing can extend from each run that requests it |
| Host class          | `--host`             | `any` by default; includes datacenter and verified community-operated hosts                                 |

`--yes` records that approval already exists. It does not create approval.
Community-operated hosts may have weaker physical and operational security.
Use `--host datacenter` when the source or environment values require
datacenter-only handling.

For auto-acquired compute, the maximum exposure is the hourly ceiling multiplied
by the command deadline plus any warm reuse window. For example, an 8-hour warm
window at $1.50/hour adds up to $12 of exposure even when no command is running.

## Forward workload secrets explicitly [#forward-workload-secrets-explicitly]

Amics does not read the agent login, Git credentials, SSH keys, cloud
credentials, or model credentials from their standard locations. A credential
inside the selected source snapshot still goes remote, as does an environment
value explicitly named by the caller. Forward one value by local name only when
the workload needs it:

```bash
export HF_TOKEN=...
amics run [OPTIONS] --env HF_TOKEN -- python train.py
```

Do not place secrets in command arguments. In particular, `--api-key` can leak
through process listings, shell history, and CI logs; prefer `AMICS_API_KEY` or
the saved login. The remote command can still leak a forwarded value if it
prints it. `--env` keeps the value out of arguments and run records, but does not
hide it from the remote host; use `--host datacenter` for sensitive credentials.

For a multi-run loop, request `--keep-warm` only on the priming run. Reuse its
`compute_id` on later runs without repeating `--keep-warm`, or obtain renewed
approval for a longer window.

## Treat unknown as possibly executed [#treat-unknown-as-possibly-executed]

If Amics cannot prove the command outcome after an interruption, the run becomes
`unknown`. Inspect the accepted run:

```bash
amics runs get RUN_ID
amics runs logs RUN_ID --follow
```

Do not submit a replacement until a person or policy decides that replay is
safe. This matters for commands with non-repeatable side effects.

## Separate cleanup decisions [#separate-cleanup-decisions]

* Auto-acquired compute stops after the command unless a warm lease was approved.
* `--detach` does not extend the command or warm deadline.
* Compute passed with `--compute` is user-supplied and is not stopped implicitly.
* `amics runs cancel RUN_ID --stop-compute` is appropriate only when stopping
  the resource is also intended.

## Agent checklist [#agent-checklist]

Before execution, an agent should be able to state the command, source root,
GPU requirement, price ceiling, command deadline, warm lease, forwarded
environment names, host class, output mode, and cleanup behavior.

---

# Use Amics from a coding agent

Give an agent a provider-neutral way to run GPU workloads while the agent and its saved login stay local.

Canonical: https://docs.amics.ai/agents

The agent stays in the local repository where it can edit, test, compare
results, and commit. Amics handles one bounded remote command at a time.

## Recommended setup [#recommended-setup]

1. Install the standalone `amics` CLI and run `amics login`.
2. Install the Amics agent skill.
3. Ask the agent to inspect the live GPU options and choose for the workload.
4. Approve an explicit maximum hourly price, runtime, and optional warm window.
5. Let the agent run the command and inspect the durable result.

```text
Use the Amics skill to compare live GPU options for this training command.
Do not acquire compute yet. I need at least 24 GB VRAM for about 30 minutes.
```

After reviewing the agent's choice:

```text
Approved up to $1.50/hour for a 30-minute command.
Run `uv run train.py`, keep the machine warm for at most 10 minutes,
and stop if the run becomes unknown.
```

## What the skill teaches [#what-the-skill-teaches]

* GPU options are read-only; choosing and acquiring are separate decisions.
* Non-interactive runs need explicit price and runtime bounds.
* Source snapshots exclude common secrets and never replace the local tree.
* Environment values are forwarded only when named with `--env`.
* Auto-acquired compute stops by default; warm reuse is a bounded lease.
* Interrupted or ambiguous runs are inspected, never replayed automatically.

## Agent boundary [#agent-boundary]

Agents stay local, forward only explicitly named workload environment values,
keep GPU selection separate from spend approval, and pause for a replay decision
when an `unknown` run may already have executed.

<Cards>
  <Card title="Install the skill" href="/agents/install-skill">
    Add the Amics workflow to a supported coding agent.
  </Card>

  <Card title="Approval and safety" href="/agents/approval-and-safety">
    Understand the exact decisions an agent must surface.
  </Card>

  <Card title="Autoresearch guide" href="/guides/autoresearch">
    Reuse bounded warm compute across a local experiment loop.
  </Card>
</Cards>

---

# Install the Amics skill

Install the Amics workflow for Codex, Claude Code, Cursor, OpenCode, or another Agent Skills-compatible client.

Canonical: https://docs.amics.ai/agents/install-skill

The Amics CLI includes a portable Agent Skill with the execution workflow,
approval rules, lifecycle behavior, and on-demand command references.

## Choose where to install [#choose-where-to-install]

After installing the CLI:

```bash
amics skill install
```

The command detects local coding agents and asks which ones should receive the
skill. Choose one or more targets, then review the plan before accepting it.

## Target specific agents [#target-specific-agents]

```bash
amics skill install --agent codex
amics skill install --agent claude-code --agent opencode
amics skill install --agent universal
```

Use `--copy` when symlinks are unavailable. Add `--yes` only when you have
already reviewed the source and installation targets. Run
`amics skill install --help` for the supported agent names.

The universal `~/.agents/skills/amics` target is installed only when selected
explicitly. Choosing a specific agent removes an older shared Amics installation.

## Plugin formats [#plugin-formats]

Plugin-aware clients can load the same workflow from the public catalog in two
formats:

| Format            | Manifest                    |
| ----------------- | --------------------------- |
| Agent Plugins 1.0 | `plugin.json`               |
| Codex             | `.codex-plugin/plugin.json` |

Both manifests expose the existing `skills/amics` package. They do not
configure an MCP server or replace the local CLI: install `amics` and use
`amics login` for authentication as usual.

## Verify the workflow [#verify-the-workflow]

Start a new agent session so it reloads installed skills, then ask:

```text
Use the Amics skill to compare live GPU capacity for a 20-minute command
that runs a CUDA application requiring at least 24 GB VRAM and compute
capability 8.0. Do not acquire anything.
```

A correct response should use `amics gpu options`, keep the action read-only,
compare only families that meet both requirements, explain what remains unknown
about application performance, and avoid turning that comparison into approval.

## Use without a skill-aware client [#use-without-a-skill-aware-client]

Give the agent these docs and the CLI:

```text
Read https://docs.amics.ai/llms.txt and
https://docs.amics.ai/agents/approval-and-safety.md before using `amics`.
```

The CLI is the execution interface. There is no production Amics MCP server in
the current contract.

## Source [#source]

The skill lives at
[`skills/amics/SKILL.md`](https://github.com/amics-ai/skills/tree/main/skills/amics)
in the public catalog. Its `references/` folder ships alongside it and is read
only when a task needs it. The catalog root is also a portable Agent Plugins
package and contains the Codex-specific manifest described above.

---

# Amics CLI

A standalone, provider-neutral executable for bounded remote GPU commands, durable runs, and compute.

Canonical: https://docs.amics.ai/cli

The `amics` CLI is the primary interface for people, coding agents, and CI. It
ships as one executable and uses the credential saved by `amics login` or the
`AMICS_API_KEY` environment variable.

Install the current stable release with the official installer:

```bash
curl -fsSL https://downloads.amics.ai/cli/install.sh | sh
amics login
amics --help
```

The installer selects the executable for the current OS and architecture,
verifies its release checksum, and replaces the destination atomically. macOS
releases are Developer ID signed and notarized. Use `--version VERSION` to pin
a release or `--install-dir DIRECTORY` to choose another destination.

## Command map [#command-map]

| Goal                              | Command                                                           |
| --------------------------------- | ----------------------------------------------------------------- |
| Sign in                           | `amics login`                                                     |
| Validate the active credential    | `amics auth status`                                               |
| Revoke the active credential      | `amics auth logout`                                               |
| Diagnose local setup              | `amics doctor`                                                    |
| Install shell completion          | `amics completion SHELL`                                          |
| Update the CLI                    | `amics update`                                                    |
| Install or update the agent skill | `amics skill install`                                             |
| Inspect live GPU options          | `amics gpu options`                                               |
| Run a project command             | `amics run [OPTIONS] -- COMMAND`                                  |
| Start a bounded HTTP service      | `amics serve [OPTIONS] -- COMMAND`                                |
| Inspect or stop a service         | `amics services get SERVICE_ID`, `amics services stop SERVICE_ID` |
| List recent runs                  | `amics runs list`                                                 |
| Inspect a run                     | `amics runs get RUN_ID`                                           |
| Read or follow logs               | `amics runs logs RUN_ID`                                          |
| Cancel a run                      | `amics runs cancel RUN_ID`                                        |
| List reusable compute             | `amics compute list`                                              |
| Stop a compute resource           | `amics compute stop COMPUTE_ID`                                   |

## Authentication order [#authentication-order]

The CLI uses the first available credential:

1. `--api-key KEY`
2. `AMICS_API_KEY`
3. The credential saved by `amics login`

Prefer `AMICS_API_KEY` or the saved credential. Command-line values can leak
through process listings, shell history, and CI logs; use `--api-key` only when
those arguments are private.

Global options may appear before the command or among its options. Arguments
after `amics run --` always remain literal.

Use `--control-url` only for an explicitly configured Amics environment. Normal
clients use `https://api.amics.ai`.

## Check or remove the CLI credential [#check-or-remove-the-cli-credential]

```bash
amics auth status
amics auth logout
```

Logout revokes the active CLI key before deleting its saved copy. If the
control plane is unreachable, `amics auth logout --local-only` removes only the
local file; the remote key remains valid until separately revoked.

Run `amics doctor` for one setup report covering the executable, credential,
control plane, agent skill, and `PATH`.

## Install and upgrade [#install-and-upgrade]

Run `amics update` to download, verify, and atomically install the current
stable release. Rerun the installer with `--version VERSION` when a specific
release is required.

Supported release targets include macOS arm64/x64 and Linux arm64/x64 builds for
standard glibc and x64 musl environments. Every versioned archive includes a
checksum manifest; verify it before replacing the executable.

<Cards>
  <Card title="Run commands" href="/cli/run">
    Choose source, GPU bounds, environment values, output, and lifecycle.
  </Card>

  <Card title="Manage runs" href="/cli/runs">
    Reconnect, follow output, cancel, and handle ambiguous outcomes.
  </Card>

  <Card title="Complete reference" href="/reference/cli">
    See command syntax, options, output modes, and exit statuses.
  </Card>
</Cards>

---

# Run a project command

Snapshot a local source tree, execute literal arguments on bounded GPU compute, stream output, and clean up safely.

Canonical: https://docs.amics.ai/cli/run

## Start with live options [#start-with-live-options]

```bash
amics gpu options --gpus 1 --min-vram 24 --max-runtime 30m
```

The command returns independent options with exact GPU family, memory, location,
live capacity depth, price, and quote expiry. Choose a family based on the
workload; Amics does not rank unlike GPUs.

The table uses display labels. Remove spaces from the chosen label when passing
its identifier to `amics run` (`RTX 4090` becomes `RTX4090`).

All verified hosts are available by default, including community-operated
machines. To restrict both discovery and acquisition to datacenter capacity,
pass `--host datacenter` to both commands:

```bash
amics gpu options --host datacenter --min-vram 24 --max-runtime 30m
amics run --host datacenter [OPTIONS] -- uv run train.py
```

Community-operated hosts may have weaker physical and operational security.
Use `datacenter` for sensitive source or forwarded environment values.

## Execute [#execute]

```bash
amics run \
  --project fine-tune \
  --source . \
  --gpu RTX4090 --gpus 1 --min-vram 24 \
  --max-hourly-price 1.50 --max-runtime 30m \
  --yes \
  -- uv run train.py
```

The project name creates a stable reuse identity. The source defaults to the
current directory.

## Install Python libraries [#install-python-libraries]

For a project dependency, add it to the project locally so its manifest and
lockfile are included in every snapshot:

```bash
uv add transformers
amics run [OPTIONS] -- uv run train.py
```

For a library needed by only one run, let `uv` provide it without changing the
project:

```bash
amics run [OPTIONS] -- uv run --with transformers train.py
```

The remote runtime includes Python and `uv`. Installing into the remote source
copy does not update the local project or a later snapshot.

## Literal arguments and shell behavior [#literal-arguments-and-shell-behavior]

Arguments after `--` are passed as literal process arguments. Pipes, redirects,
globs, expansion, and command chaining do not happen implicitly.

Use a shell explicitly when shell behavior is part of the command:

```bash
amics run [OPTIONS] -- sh -lc 'uv run train.py | tee remote.log'
```

## Source snapshots [#source-snapshots]

Inside Git, the snapshot includes tracked and untracked files after standard
ignore rules and `.amicsignore`. Amics excludes `.git`, common secret files,
unsafe links, and traversal paths; `.amicsignore` can exclude a symlink before
it is selected. Outside Git, traversal rejects any symlink before
`.amicsignore` can filter it, so remove or relocate the link or snapshot a Git
worktree instead.

Each run receives an immutable snapshot. Remote changes do not overwrite the
local source tree and are not used in the next run.

## Environment values [#environment-values]

Forward values explicitly by local name:

```bash
export DATA_TOKEN=...
amics run [OPTIONS] --env DATA_TOKEN -- python train.py
```

Repeat `--env` for multiple names. Do not put secrets in command arguments.

## Output modes [#output-modes]

| Mode       | Behavior                                                     |
| ---------- | ------------------------------------------------------------ |
| Default    | Lifecycle stages plus process output                         |
| `--quiet`  | Exact stdout/stderr bytes and the remote process exit status |
| `--json`   | One terminal run object                                      |
| `--jsonl`  | Structured stages and base64-encoded process frames          |
| `--detach` | Return the durable run while it continues remotely           |

Only one of `--quiet`, `--json`, or `--jsonl` may be selected. Detaching does
not extend the server deadline.

Default output follows redacted runtime setup logs while the machine prepares,
then continues with command output. Quiet and structured modes keep their
existing byte-exact or machine-readable contracts.

## Reuse compute briefly [#reuse-compute-briefly]

```bash
amics run [OPTIONS] --keep-warm 10m -- uv run train.py
```

A warm lease lets later compatible commands with the same project reuse the
machine and its project cache. The lease expiry is calculated from each run's
completion time, so repeating the full `--keep-warm` duration can extend the
approved billing window. For multiple experiments, request the warm lease on
the first run, capture its `compute_id`, and use that ID without
`--keep-warm` on later runs:

```bash
amics run --compute COMPUTE_ID --max-runtime 10m -- uv run train.py
```

Keep `--host datacenter` on later runs when the workload requires that constraint.

It is bounded and can still end early if Spot capacity is interrupted. Without
`--keep-warm`, auto-acquired compute stops after the command.

Use `--compute COMPUTE_ID` to run on compute you already control. Amics will not
stop user-supplied compute implicitly.

## Choose disk size [#choose-disk-size]

Use `--storage GB` for the attached disk on each machine. The default is 50 GB;
you can request 1–10,000 GB, subject to live capacity. Include space for model
weights, encoders, installed dependencies, temporary downloads, and outputs.

```bash
amics gpu options --min-vram 24 --storage 200
amics run --gpu RTX4090 --storage 200 --max-hourly-price 1.50 --max-runtime 30m -- ./generate.sh
```

Use the same size when checking prices and launching: the hourly quote and
price ceiling include storage. `amics serve` also accepts `--storage`.
A warm machine is reused only if its disk meets the request. This selects the
size for a new machine; it does not resize an existing machine or make its
files persistent. Transfer outputs before stopping compute.

---

# Durable runs and output

Inspect accepted commands, follow byte-exact output, cancel one generation, and recover safely after interruption.

Canonical: https://docs.amics.ai/cli/runs

Every accepted command has a durable run ID. Keep and reuse that ID instead of
submitting another command when a network connection drops.

## Inspect and follow [#inspect-and-follow]

```bash
amics runs list
amics runs get RUN_ID
amics runs logs RUN_ID --follow
```

`runs list` recovers recent run IDs after closing a terminal or detaching.
Settled run objects include `attributed_spend_microusd`; warm idle time is
excluded from this per-run attribution, and overlapping commands share metered
lease intervals. Warm idle time is still billed to the lease until its approved
deadline or until the compute is stopped.

Output cursors are opaque. To resume from the last acknowledged position:

```bash
amics runs logs RUN_ID --cursor OPAQUE_CURSOR --follow
```

Use `--jsonl` on `runs logs` for structured frames.

In the default human-readable `--follow` view, Amics also prints redacted
runtime setup logs while the run is starting. `--jsonl` remains limited to
structured command-output frames.

## Run states [#run-states]

`queued`, `acquiring`, `syncing`, `starting`, `running`, `succeeded`, `failed`,
`cancelling`, `cancelled`, and `unknown`.

`unknown` means Amics cannot prove the command outcome. The command may have
executed. Inspect the run and its output before deciding whether another
submission is safe.

## Cancel [#cancel]

```bash
amics runs cancel RUN_ID
```

Cancellation targets the current run generation. Supply an exact generation
when coordinating with another caller:

```bash
amics runs cancel RUN_ID --generation GENERATION
```

Add `--stop-compute` only when the compute resource should stop too. A cancelled
remote process returns exit status `130`.

## Interrupting the local CLI [#interrupting-the-local-cli]

During an attached run, the first Ctrl-C requests cancellation of the current
generation. A second Ctrl-C detaches the local CLI while the server state
remains inspectable.

## Stop retained compute [#stop-retained-compute]

```bash
amics compute list
amics compute stop COMPUTE_ID
```

Use `compute list` to recover reusable lease IDs. Stop the exact compute ID
returned by the run when ending an approved warm reuse window early.

---

# Compute model

How Amics selects capacity, snapshots source, reuses warm cache, and cleans up compute.

Canonical: https://docs.amics.ai/compute

## Capacity [#capacity]

Amics ranks current compatible Spot GPU capacity against the requested GPU
family, count, minimum VRAM, location, preference, runtime, and optional maximum
hourly price.

Capacity results are observations, not reservations of a particular machine.
When a run is accepted, Amics records the exact GPU family, count, minimum VRAM,
location, host class, and price ceiling as an immutable acquisition policy. Each
initial launch and Spot recovery resolves fresh physical capacity against that
policy. A recovery may use a different machine or backing provider, but it never
substitutes another GPU family or widens the approved bounds.

Without `--location`, selection can use capacity anywhere and keeps alternatives
available during bounded acquisition retries. Explicit locations are hard
constraints and are never widened.

Host class is also a hard constraint. `any` is the default and includes both
datacenter and verified community-operated hosts. `--host datacenter` restricts
selection to datacenter capacity; retries never widen that request to community
capacity.

Spot capacity is interruptible. Amics records the run as durable state but does
not replay a command whose completion cannot be proved. Managed infrastructure
recovery stays within the same run; reconnect to that run instead of submitting
a replacement.

## Project identity and warm cache [#project-identity-and-warm-cache]

A stable `--project` value lets compatible commands reuse a machine during an
approved warm lease. The remote project directory backs:

* `$HOME/.cache`
* `$UV_CACHE_DIR`
* `$AMICS_CACHE_DIR`
* `$AMICS_WORKSPACE`

These paths survive while that compute remains warm. They disappear when the
machine stops or is preempted.

## Compute lifecycle [#compute-lifecycle]

| Input                            | Cleanup behavior                                  |
| -------------------------------- | ------------------------------------------------- |
| Auto-acquired run                | Stops after the command by default                |
| Auto-acquired with `--keep-warm` | May remain until the bounded lease expires        |
| `--detach`                       | Run continues, deadlines unchanged                |
| User-supplied `--compute`        | Resource remains running until explicitly stopped |

## Data lifecycle [#data-lifecycle]

Default runs do not create persistent storage. Put large or reusable datasets in
external storage.

<Cards>
  <Card title="Run a command" href="/cli/run">
    Apply compute bounds and choose the lifecycle explicitly.
  </Card>
</Cards>

---

# Quickstart

Install the standalone CLI, sign in, inspect live capacity, and run a local command on a bounded remote GPU.

Canonical: https://docs.amics.ai/getting-started/quickstart

## 1. Install the CLI [#1-install-the-cli]

```bash
curl -fsSL https://downloads.amics.ai/cli/install.sh | sh
amics --version
```

The installer selects a standalone executable for macOS or Linux, verifies its
checksum, and installs it to `~/.local/bin`. macOS executables are signed and
notarized. The CLI does not require Bun, Node.js, Python, or a package manager
at runtime.

On a first interactive install, accept the prompt to complete sign-in and skill
installation now. If you accept, skip steps 2 and 3 below.

## 2. Sign in [#2-sign-in]

```bash
amics login
```

The CLI opens a short-lived browser approval flow and stores the workspace
credential with private file permissions. For a headless machine:

```bash
amics login --no-browser
```

Open the printed URL on another device. In CI, set `AMICS_API_KEY` instead.

## 3. Install the agent skill [#3-install-the-agent-skill]

```bash
amics skill install
```

The CLI detects local coding agents and asks where to install the skill. Use
`--agent codex` or another supported agent name to choose targets explicitly,
`--agent universal` for `~/.agents/skills`, or `--copy` when symlinks are
unavailable.

The installed package follows the portable Agent Skills layout used by
skills.sh, so supported agents can discover the same `SKILL.md`. The public
catalog also includes Agent Plugins 1.0 and Codex manifests for plugin-aware
clients; both load this skill and still use the local CLI for execution.

## 4. Start with your agent [#4-start-with-your-agent]

Ask your coding agent:

```text
Use $amics to compare live GPU options for this workload. Ask before acquiring compute.
```

Or run the CLI directly:

```bash
amics gpu options --min-vram 24 --max-runtime 30m

# Replace this placeholder with a family returned above, without spaces.
amics run \
  --gpu CHOSEN_GPU_IDENTIFIER --min-vram 24 \
  --max-hourly-price 1.50 --max-runtime 30m \
  -- nvidia-smi --query-gpu=name,memory.total --format=csv,noheader
```

The options command prints current family labels and prices. Choose a family
that fits the workload, then remove spaces from its label for `--gpu` (`RTX
4090` becomes `RTX4090`). Replace the example price and runtime with bounds you
are prepared to approve.

By default, discovery and execution include all verified hosts, including
community-operated machines. Use `--host datacenter` on both commands for
sensitive source or forwarded environment values.

`--max-hourly-price` is the maximum total compute rate in USD per hour.
`--max-runtime` bounds the command. Arguments after `--` are passed literally.
The interactive run shows its acquisition plan and asks for confirmation. A
successful smoke run prints the detected GPU name and memory, then stops the
auto-acquired compute.

For an unattended run, add `--yes` only after a person or explicit policy has
approved the complete acquisition envelope. The caller must provide all three
of `--yes`, `--max-hourly-price`, and `--max-runtime`.

## 5. Know what happens next [#5-know-what-happens-next]

Amics snapshots the selected project, acquires compatible Spot capacity, runs
the command, streams stdout and stderr, and stops auto-acquired compute after
the command. Spot capacity can be interrupted. Amics keeps the run and its logs
for inspection but never blindly submits a second copy.

## Troubleshoot setup [#troubleshoot-setup]

Start with:

```bash
amics doctor
```

It validates the CLI, credential, control plane, agent skill, and `PATH`, and
prints the exact fix for each failed check. If the dashboard still does not
advance:

1. Run `amics --version`. If the command is missing, add `~/.local/bin` to
   `PATH` or run the installer again.
2. Run `amics login` again and complete the browser authorization. A successful
   login connects the CLI to the workspace shown in the browser.
3. Run `amics skill install --help` to see supported agents, then rerun
   `amics skill install`. Reinstalling updates the canonical skill safely.
4. Use **Check again** in the dashboard. It continues retrying automatically
   after temporary control-plane or network failures.

<Cards>
  <Card title="Run options" href="/cli/run">
    Source selection, environment values, shell behavior, output, and warm reuse.
  </Card>

  <Card title="Set up an agent" href="/agents/install-skill">
    Install the policy-aware Amics skill for your coding agent.
  </Card>
</Cards>

---

# Run an autoresearch loop

Keep experiment decisions and Git local while reusing one bounded warm GPU across repeated commands.

Canonical: https://docs.amics.ai/guides/autoresearch

Use one stable project name and an approved warm lease. The agent edits,
commits, parses results, and chooses the next experiment locally. Amics runs
each training command on the remote machine.

## 1. Approve the loop [#1-approve-the-loop]

Establish a maximum hourly rate, per-command runtime, total warm window, GPU
requirement and environment names. The warm window is the
maximum time compute may remain available, not a guarantee of uninterrupted Spot
capacity. Maximum exposure is the hourly ceiling multiplied by the command
deadline plus the warm window. At the example $1.50/hour ceiling, an 8-hour
warm window adds up to $12 even while the machine is idle.

Inspect `amics gpu options --min-vram 24 --max-runtime 10m`, then choose an
exact family for the workload.

## 2. Prepare the cache [#2-prepare-the-cache]

```bash
amics run \
  --project autoresearch \
  --gpu RTX4090 --min-vram 24 \
  --max-hourly-price 1.50 --max-runtime 10m \
  --keep-warm 8h --yes --json \
  -- sh -lc 'mkdir -p "$AMICS_CACHE_DIR/autoresearch" && test -w "$AMICS_CACHE_DIR/autoresearch"' \
  > .amics-autoresearch-lease.json
```

Read the returned `id` and `compute_id`. Keep the local control file out of Git.

## 3. Run each experiment [#3-run-each-experiment]

Edit and commit the experiment locally, then reuse the captured compute ID. Do
not repeat `--keep-warm 8h`: each auto-acquired run sets its lease expiry from
its own completion time, so repeating the full warm duration can extend the
approved billing window.

```bash
amics run \
  --compute COMPUTE_ID \
  --max-runtime 10m \
  -- uv run train.py > run.log 2> run.meta.log
```

Parse the process output in `run.log` locally and decide the next edit.
`run.meta.log` contains remote stderr, CLI stage messages, the durable run ID,
and the terminal status. The captured compute keeps the same warm machine and
cache without requesting a new warm lease.

## 4. Stop on ambiguity [#4-stop-on-ambiguity]

If the CLI exits `75`, do not assume the outcome is unknown. Read the run ID
from `run.meta.log`, then inspect `amics runs get RUN_ID` and its logs. A remote
process can also return `75`; use the run's status and exit fields to decide.
Do not launch the next experiment until replay is known to be safe.

## 5. End the lease early [#5-end-the-lease-early]

```bash
amics compute stop COMPUTE_ID
```

Stopping compute deletes its default project directory and cache.

---

# CLI overview

Command surface, output modes, and exit statuses for the standalone amics executable.

Canonical: https://docs.amics.ai/reference/cli

## Global [#global]

```text
amics [global options] <command>
```

| Option              | Purpose                                                                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `--api-key KEY`     | Override `AMICS_API_KEY` and the saved login; avoid normal use because argv can leak into process listings, shell history, and CI logs |
| `--control-url URL` | Override the Amics control-plane URL                                                                                                   |
| `--timeout SECONDS` | Request timeout; default `30`                                                                                                          |
| `--help`, `-h`      | Show help                                                                                                                              |
| `--version`, `-v`   | Show version                                                                                                                           |

Global options may appear before the command or among its options. They are
never parsed after the literal `--` separator used by `amics run` and `amics serve`.

## Updates and agent skill [#updates-and-agent-skill]

```text
amics update
amics skill install [--agent AGENT] [--copy] [--yes]
```

`update` downloads, verifies, and atomically installs the current stable CLI.
`skill install` asks which agents should receive the bundled skill. Repeat
`--agent` to choose targets explicitly, select `--agent universal` for
`~/.agents/skills/amics`, or use `--copy` where symlinks are unavailable.

## `login` [#login]

```text
amics login [--no-browser]
```

## Authentication and setup [#authentication-and-setup]

```text
amics auth status [--json]
amics auth logout [--local-only] [--yes]
amics doctor [--json]
```

`auth logout` revokes the active CLI key, then removes its matching saved copy.
`--local-only` skips revocation for offline recovery. `doctor` checks the CLI
build, credential, control plane, agent skill, and `PATH`.

## Shell completion [#shell-completion]

```text
amics completion bash
amics completion fish
amics completion zsh
```

Redirect the output to the completion directory used by your shell.

## `gpu options` [#gpu-options]

```text
amics gpu options [GPU OPTIONS] [--max-runtime DURATION]
```

This read-only command prints a table of live options. Pass `--json` for a JSON
array. Each option describes one exact family, location, price, capacity depth,
and quote expiry. The command does not rank unlike GPU families or select one
for execution. Remove spaces from a displayed family before passing it to
`amics run --gpu` (`RTX 4090` becomes `RTX4090`).

## `run` [#run]

```text
amics run [OPTIONS] -- COMMAND [ARG...]
```

| Option                   | Purpose                                                 |
| ------------------------ | ------------------------------------------------------- |
| `--project NAME`         | Stable project identity for compatible reuse            |
| `--source PATH`          | Local source root; default `.`                          |
| `--compute ID`           | Use existing compute; it will not stop implicitly       |
| `--max-runtime DURATION` | Bound command execution                                 |
| `--keep-warm DURATION`   | Bound post-command compute reuse                        |
| `--env NAME`             | Forward one local environment value; repeatable         |
| `--detach`               | Return while the durable run continues                  |
| `--yes`                  | State that explicit acquisition approval already exists |
| `--quiet`                | Exact process bytes and remote exit status              |
| `--json`                 | One terminal run object                                 |
| `--jsonl`                | Structured stages and base64 output frames              |

Run durations must be at least 60 seconds and may be at most 24 hours. The
default is one hour. `--keep-warm` may be at most 24 hours and cannot be used
with `--compute`. Use `amics run --help` for the authoritative option list and
validation rules for the installed version.

Default human-readable output follows redacted runtime setup logs during the
`starting` stage before command output begins. Quiet, JSON, and JSONL modes do
not include this extra setup stream.

`--storage GB` selects 1–10,000 GB of attached disk for `run`, `serve`, and
`gpu options` (default: 50 GB). Quotes include the requested storage.

## GPU options [#gpu-options-1]

`amics gpu options` prints supported market prices and marks options with live
capacity. Add `--available` to show only GPUs currently eligible to launch from
marketplace availability or cloud quota signals, or `--json`
for structured output.

| Option                   | Values                                                                                              |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| `--available`            | Show only GPUs currently eligible to launch                                                         |
| `--json`                 | Emit structured output instead of a table                                                           |
| `--gpu FAMILY`           | Exact accelerator family; remove spaces from display labels for `amics run`                         |
| `--gpus COUNT`           | Positive integer; default `1`                                                                       |
| `--storage GB`           | Attached disk per machine; 1–10,000 GB, default `50`; use the same size for discovery and execution |
| `--min-vram GB`          | Minimum VRAM per GPU                                                                                |
| `--location LOCATION`    | `europe` or `united_states`                                                                         |
| `--host CLASS`           | `any` (default) or `datacenter`; `any` includes verified community-operated hosts                   |
| `--max-hourly-price USD` | Maximum total compute rate                                                                          |

Durations accept `s`, `m`, `h`, or `d`.

## `serve` and `services` [#serve-and-services]

```text
amics serve [GPU OPTIONS] --max-hourly-price USD --ttl DURATION \
  [--port PORT] [--health-path PATH] [--env NAME] [--yes] -- COMMAND [ARG...]
amics services get SERVICE_ID
amics services stop SERVICE_ID
```

`serve` snapshots the current project and starts one HTTP process as a bounded
run. `--ttl` is required, `--port` defaults to `8000`, and `--health-path`
defaults to `/health`. The printed URL becomes usable when `services get`
reports `service.status` as `ready`. Authenticate requests to that URL with the
same Amics API key; Amics removes it before forwarding to the application.

For an OpenAI-compatible server, append `/v1` to the printed URL:

```bash
BASE_URL=$(amics serve --gpu L40S --max-hourly-price 1.50 --ttl 8h --yes -- \
  uv run vllm serve Qwen/Qwen3-8B --port 8000)
curl -H "Authorization: Bearer $AMICS_API_KEY" "$BASE_URL/v1/models"
```

The service and its compute stop at the TTL even if the client disconnects.
`services stop` releases them earlier.

## Runs and compute [#runs-and-compute]

```text
amics runs list
amics runs get RUN_ID
amics runs logs RUN_ID [--cursor CURSOR] [--follow] [--jsonl]
amics runs cancel RUN_ID [--generation NUMBER] [--stop-compute]
amics services get SERVICE_ID
amics services stop SERVICE_ID
amics compute list [--json]
amics compute stop COMPUTE_ID
```

`runs list` recovers recent run IDs and `compute list` recovers reusable lease
IDs, so detached work never depends on terminal scrollback.

`runs logs` without `--follow` returns one bounded page. Use `--follow` to read
through the current end. To resume a paged read, add `--jsonl`, copy the opaque
`cursor` from the last output frame, then pass it to the next invocation:

```text
amics runs logs RUN_ID --jsonl
amics runs logs RUN_ID --cursor OPAQUE_CURSOR --jsonl
```

Human-readable `--follow` also prints redacted runtime setup logs while the run
is starting. JSONL preserves its command-output frame schema.

## Exit statuses [#exit-statuses]

| Status  | Meaning                                                                       |
| ------- | ----------------------------------------------------------------------------- |
| `0–255` | Remote process status, or `128 + signal`, when the run result reports it      |
| `64`    | CLI validation, authentication, snapshot, or 4xx failure; no run was acquired |
| `70`    | CLI reports a failed run with no exit code or signal                          |
| `75`    | CLI reports `unknown`, or the control plane was unreachable                   |
| `130`   | CLI reports a cancelled run                                                   |

A remote process can itself return `64`, `70`, `75`, or `130`. When a run ID
exists, inspect `amics runs get RUN_ID` and use its `status`, `exit_code`,
`termination_signal`, and `failure` fields before interpreting an overlapping
status. Never replay an `unknown` run automatically.

---

# HTTP endpoints

Base URL, authentication, idempotency, and the public compute routes used by the CLI and direct integrations.

Canonical: https://docs.amics.ai/reference/endpoints

## Base URL and authentication [#base-url-and-authentication]

```text
https://api.amics.ai
```

```http
Authorization: Bearer amics_sk_...
Content-Type: application/json
```

Use a workspace API key. Do not put it in source, command arguments, or logs.
The complete request, response, and error schemas are published in the
[`OpenAPI document`](https://api.amics.ai/openapi.json).

## Read live GPU options [#read-live-gpu-options]

This request is read-only and does not acquire compute:

```bash
curl --fail-with-body https://api.amics.ai/v1/platform/compute/gpu-options \
  --header @- \
  --data '{"gpu_count":1,"minimum_gpu_memory_gb":24,"expected_duration_seconds":1800}' <<EOF
Authorization: Bearer $AMICS_API_KEY
Content-Type: application/json
EOF
```

The shell expands the API key into curl's standard input, not its process
arguments. Keep shell tracing disabled anywhere secret input could be recorded.

The response contains independent provider-neutral options. Select a family
using the workload's architecture and feature requirements before creating a
snapshot or run.

## Command execution [#command-execution]

| Method and path                                                                | Purpose                                         |
| ------------------------------------------------------------------------------ | ----------------------------------------------- |
| `POST /v1/platform/compute/gpu-options`                                        | List supported GPU prices and live availability |
| `POST /v1/platform/compute/source-snapshots`                                   | Create or resume a source snapshot              |
| `GET /v1/platform/compute/source-snapshots/{snapshot_id}`                      | Inspect upload state                            |
| `PUT /v1/platform/compute/source-snapshots/{snapshot_id}/chunks/{chunk_index}` | Upload a checksummed binary chunk               |
| `POST /v1/platform/compute/runs`                                               | Accept a durable command run                    |
| `GET /v1/platform/compute/runs`                                                | List and filter durable runs                    |
| `GET /v1/platform/compute/runs/{run_id}`                                       | Inspect command and cleanup state               |
| `GET /v1/platform/compute/runs/{run_id}/runtime-logs/stream`                   | Read redacted runtime setup logs                |
| `GET /v1/platform/compute/runs/{run_id}/output`                                | Read a bounded output page                      |
| `GET /v1/platform/compute/runs/{run_id}/output/stream`                         | Follow newline-delimited output                 |
| `POST /v1/platform/compute/runs/{run_id}/cancel`                               | Cancel one run generation                       |

`POST /v1/platform/compute/runs` requires an `Idempotency-Key` header. Preserve
the same key and body when recovering from a lost response.

Set `constraints.storage_gb` when creating a run, and `storage_gb` when
requesting GPU options or recommendations. The value is an integer from 1 to
10,000, defaults to 50 GB, and is included in the hourly price ceiling. A
provided or warm machine must already have enough disk; it is not resized.

Source chunks use `application/octet-stream` and
`X-Amics-Chunk-Sha256`. Output cursors are opaque and must be returned
unchanged.

Runtime setup logs are plain text, tenant-scoped, and redacted before they
leave the control plane. Pass `follow=false` for a bounded snapshot and `tail`
from `1` to `1000` to choose the maximum number of recent lines.

Run list and detail responses include `attributed_spend_microusd` after metered
charges settle. Warm idle time is excluded from per-run attribution but remains
billed to the lease; overlapping commands share the lease interval.

## Reusable compute [#reusable-compute]

| Method and path                                    | Purpose                         |
| -------------------------------------------------- | ------------------------------- |
| `GET /v1/platform/compute/leases`                  | List reusable compute leases    |
| `POST /v1/platform/compute/leases`                 | Create a reusable compute lease |
| `GET /v1/platform/compute/leases/{lease_id}`       | Inspect a compute lease         |
| `PATCH /v1/platform/compute/leases/{lease_id}`     | Rename a compute lease          |
| `POST /v1/platform/compute/leases/{lease_id}/stop` | Stop a compute lease            |
| `DELETE /v1/platform/compute/leases/{lease_id}`    | Stop a compute lease            |

Historical `/v1/platform/training` routes remain deprecated compatibility
aliases for released clients. New integrations should use compute leases.

For reusable multi-node leases, `gpu_count`, `cpu_count`, `memory_gb`, and
`storage_gb` describe each identical node. Lease responses include explicit
`total_*` resource fields. `estimated_hourly_price_usd_per_node` includes one
node's compute and attached storage; `estimated_hourly_price_usd` is the retail
rate for the full cluster. Credit authorization, metering, and GPU quota use
the full-cluster values.

The CLI and direct HTTP API are the supported integrations. A production Amics
MCP server is not part of the current contract.

---

# Current limits

The explicit boundaries of the current Amics remote-execution contract.

Canonical: https://docs.amics.ai/reference/limits

Amics currently provides single-node, bounded remote command execution.

## Execution limits [#execution-limits]

| Boundary                            | Current maximum          |
| ----------------------------------- | ------------------------ |
| Files in one source snapshot        | 25,000                   |
| Total uncompressed snapshot content | 1 GiB                    |
| Retained output per run             | 64 MiB                   |
| Command runtime                     | 24 hours                 |
| Warm reuse window                   | 24 hours                 |
| Attached disk per machine           | 10,000 GB; default 50 GB |

The CLI performs additional checks before upload. The service limit is the
effective limit whenever it is stricter. Use external storage for datasets and
large artifacts instead of including them in every source snapshot.

It does not provide:

* a locally attached CUDA device;
* an SSH session or remote desktop;
* a live filesystem mount;
* automatic remote-to-local artifact synchronization;
* multi-node command execution through `amics run`;
* guaranteed uninterrupted Spot capacity;
* automatic replay after an ambiguous outcome;
* implicit forwarding of local credentials;
* implicit persistent storage;
* a production MCP server.

Use external storage for data that must outlive compute. Download or upload
artifacts explicitly when they must move between the local tree and the remote
environment.

These boundaries are deliberate. They keep the command, spend, data lifecycle,
and replay decision visible to both people and agents.