Bring your own compute

Bring your own compute (BYOC) runs rigs on hardware you control. You install the amika-hostd daemon on a machine, it registers that machine with Amika as a host, and each rig you create on that host runs there as a local VM.

Requirements

Linux x86_64 or arm64 with glibc 2.34+ and KVM, or macOS on Apple silicon.
e2fsprogs: smolvm makes any disk smaller than its 20 GiB template by shrinking it with resize2fs. The installer installs it when it is missing.
A way to expose one local port to the internet over HTTPS, such as ngrok or Cloudflare Tunnel.
An Amika API key. Create one under Settings → API Keys at app.amika.dev, or from the CLI during setup.

Node.js and smolvm, which the daemon needs, are installed for you when the machine doesn’t already have them.

Set up a host

Install the daemon

On the machine you want to run rigs:

curl -fsSL https://raw.githubusercontent.com/gofixpoint/amika/main/install-amika-hostd.sh | sh

See Installer options to pin a version, skip smolvm, or preview the install with --dry-run.If resize2fs is missing, the installer installs e2fsprogs. On macOS it runs brew install e2fsprogs. On Linux it uses apt-get, dnf, or yum as root or with sudo, and asks first. With --install-deps it installs without asking, but only as root or when sudo needs no password. When it can’t install, it prints a warning with the reason and the exact command to run, and the install still succeeds.The install-amika-hostd.sh script will generate a config file in $XDG_CONFIG_HOME/amika-hostd/config.toml (~/.config/amika-hostd/config.toml by default).

Store your credentials

amika-hostd setup

It asks for this host’s name and your Amika API key, and generates the secret key Amika uses to reach the daemon. Secrets go in the system keychain. On a server with no keychain, set secret_store = "file" in the config file before running setup.To set up a host without prompts, for a script or an AI agent, pipe the API key into setup --non-interactive. amika auth api-key create writes a new key straight to a file without printing it:

dir=$(mktemp -d)
amika auth api-key create --name my-host-hostd --out "$dir/api-key"
amika-hostd setup --non-interactive --hostname my-host < "$dir/api-key"
rm -rf "$dir"

--non-interactive asks nothing. It keeps any secret key the host already has, and it stops without changing anything if the hostname is invalid or no key arrives on stdin.

amika auth api-key create ships in the amika CLI release after v0.23.0. With an older CLI, create the key in the web UI and save it to a file instead.

amika-hostd setup --skill prints step-by-step instructions an AI agent can follow to set up the host, including how to get the API key without seeing it.

Start the daemon

amika-hostd up

This registers the host with Amika, starts the daemon on 127.0.0.1:3020, and starts smolvm alongside it. Pass --fg to stay in the foreground, and --port or --host to listen somewhere else (or set port and host in the config).

Give the host a public URL

Amika reaches the daemon over the internet, so expose port 3020 over HTTPS and record the URL. Using ngrok for example:

ngrok http 3020                                    # in another terminal
amika-hostd register-url https://<your-tunnel-url>

amika-hostd up prompts for this URL when the host doesn’t have one, so you can paste it there instead.

Register a bare HTTPS hostname, such as https://hostd.example.com, with no path or port. Only these hosts get browser-login previews.Other URLs still work for rigs and signed service links, but previews of apps like Vite or Next.js dev servers can break.

Create a rig on your host

CLI
Web UI
TypeScript
HTTP API

# Confirm the host registered, and see the sizes it offers
amika host list

# Create a rig on it
amika rig create --name dev-box --host my-host --size small

--size takes one of that host’s own sizes, not the cloud size names. Omit --host and the rig runs on Amika Cloud. To boot from a snapshot, add --snapshot <name>. It must be a snapshot taken on that same host (see Snapshots on your host).The first amika-hostd up downloads the preset images in the background, and a rig created before that finishes can time out. The daemon logs the progress.

Pass the host’s ID as hostId. amika host get <hostname> prints it, along with the sizes the host offers.

const hostId = "host_123"; // From `amika host get my-host`
const rig = await client.rigs.create({ name: "dev-box", hostId, size: "small" });
await rig.wait();

With hostId, size names one of that host’s own sizes. rig.hostId and rig.hostname report where a rig runs.

Send the host’s ID as host_id. size then names one of the host’s sizes.

curl -X POST https://app.amika.dev/api/v0beta1/rigs \
  -H "Authorization: Bearer $AMIKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"dev-box","host_id":"host_123","size":"small"}'

Configure sizes and images

The config file you set up above sets the rig sizes this host offers and the preset image each rig boots. Every amika-hostd up publishes the sizes to Amika, so the file is the source of truth for them. Preset images stay local: the host pins the version it boots. Edit the file and restart the daemon either way.

[sizes.small]
vcpus = 2
memory_gib = 4
disk_gib = 20

[preset_images]
amika-coder = "ghcr.io/gofixpoint/amika-coder:latest"

Keep disk_gib at 20 or more. Below that, smolvm doesn’t cache the rig’s image, so every create downloads it again.

Snapshots on your host

You can snapshot a rig that runs on your host. The snapshot is a .smolmachine file that stays on that host’s disk, and it can only boot new rigs on the same host.

Snapshot and delete is the only mode. The daemon stops the rig to pack its disks, so Snapshot everything, which keeps the source rig running, isn’t offered.
Repository and organization default snapshots don’t apply. A host rig boots its preset image unless you pick one of that host’s snapshots when you create it.
Snapshots are large. Each one is several gigabytes. Point snapshot_dir in the config (or AMIKA_HOSTD_SNAPSHOT_DIR) at a disk with room for them. By default they go under ~/.local/state/amika-hostd/snapshots.

snapshot_dir = "/var/lib/amika-hostd/snapshots"

amika snapshot list --long shows a HOST column, so you can tell which snapshots belong to which host.

Previews and service access

A rig’s services on your host are reached through the daemon, at the URL you registered. The kind of link you get in the browser depends on that URL.

Bare HTTPS hostname (such as https://hostd.example.com): each service gets a preview link. Opening it asks you to sign in to Amika, and only members of your organization get through. One sign-in lasts a day and covers every preview on the host.
Any other URL (a path, a port, plain http, or a loopback address): each service gets a signed link. Anyone with the link can open the service for a day, so share it only with people who should have access.

Previews on one host share an origin and a login, so treat a host as one trusted unit: keep code you don’t trust off a host whose other previews you open. For scripts and tools like curl, mint a short-lived service token with the HTTP API. It works only for rigs on your own hosts, never for amikad.

curl -X POST \
  "https://app.amika.dev/api/v0beta1/rigs/dev-box/services/web/tokens?ttl_seconds=900" \
  -H "Authorization: Bearer $AMIKA_API_KEY"

The response gives the service’s url, the header to send the token in (X-Amika-Authorization), the token, and expires_at. Tokens last an hour by default and at most a day.

curl -H "X-Amika-Authorization: Bearer $TOKEN" "$URL"

Manage hosts

Command	What it does
`amika host list`	List your organization’s hosts and their sizes
`amika host get <hostname>`	Show one host, its ID, and the sizes it offers
`amika host delete <hostname>`	Delete a host and its stored secret

Hosts register themselves, so there is no command to add one. A host that still has rigs on it can’t be deleted: delete the rigs first. You can also delete a host from Hosts in the sidebar. To take a host offline, run amika-hostd down on the machine. That stops the daemon and the VMs it is running, keeping their disks. The next up brings the daemon back, but not the rigs: start those with amika rig start. Deleting the host record alone leaves the machine untouched, so it registers itself again on the next amika-hostd up.

Rigs on a host that’s gone

Deleting a rig needs its host to answer. When the host is offline, the delete fails and the web UI offers Remove from Amika only. That deletes Amika’s record of the rig but leaves anything still running on the machine, which you then clean up yourself. The HTTP API does the same with DELETE /api/v0beta1/rigs/{id}?forget=true.

Uninstall the daemon

Run the installer with --uninstall on the host:

curl -fsSL https://raw.githubusercontent.com/gofixpoint/amika/main/install-amika-hostd.sh | sh -s -- --uninstall

It shows what it found and asks you to confirm, stops the daemon, and deletes the launcher and its files. It then asks separately whether to remove the config and state directory, the keychain secrets, and smolvm.

Flag	What it does
`--purge`	Also remove the config, state directory, and keychain secrets without asking. Keeps smolvm
`--yes`, `-y`	Answer yes to every question except smolvm’s. Needed without a terminal
`--dry-run`	Show what would be removed

smolvm is removed only if you type remove smolvm at its prompt. Uninstalling doesn’t remove the host from Amika: delete it with amika host delete.

Installer options

Flag	What it does
`--install-version <version>`	Install a specific `amika-hostd` version
`--dry-run`	Show what would be done without downloading or installing
`--smolvm-version <version>`	Install this smolvm version if smolvm is missing
`--skip-smolvm`	Don’t install smolvm
`--install-deps`	Install missing system packages (`e2fsprogs`) without asking, only as root or when `sudo` needs no password. Use it for scripts and AI agents
`--uninstall`	Remove `amika-hostd`. See Uninstall the daemon

Pass flags after sh -s --, for example curl -fsSL .../install-amika-hostd.sh | sh -s -- --dry-run. AMIKA_INSTALL_DIR sets where the launcher goes (default /usr/local/bin), and AMIKA_HOSTD_HOME where the daemon’s files go.

Next steps

amika host reference

Every flag for the amika host commands.

Create a rig

The full rig creation flow, on cloud or your own host.

Get started

Rigs (machines)

Agents and sessions

Configuration

Connecting to rigs

Guides for agents

Advanced

Bring your own compute

Requirements

Set up a host

Create a rig on your host

Configure sizes and images

Snapshots on your host

Previews and service access

Manage hosts

Rigs on a host that’s gone

Uninstall the daemon

Installer options

Next steps

amika host reference

Create a rig

​Requirements

​Set up a host

​Create a rig on your host

​Configure sizes and images

​Snapshots on your host

​Previews and service access

​Manage hosts

​Rigs on a host that’s gone

​Uninstall the daemon

​Installer options

​Next steps

amika host reference

Create a rig

Requirements

Set up a host

Create a rig on your host

Configure sizes and images

Snapshots on your host

Previews and service access

Manage hosts

Rigs on a host that’s gone

Uninstall the daemon

Installer options

Next steps