# smbCloud Run

> smbCloud Run is a job-execution service. You submit a job, a runner on your own hardware claims it and runs it inside a Firecracker microVM, and the logs and result come back to you. It serves two workloads on one runner: sandboxes for AI agents and isolated CI/CD.

Status: Early access
Last updated: 2026-11-06

## Features

- **Runners pull, the server never connects out.** A runner polls smbCloud for work. Nothing opens a connection to the runner, so it works from behind NAT with no port forwarding, including on a Mac at home.
- **Firecracker microVMs from a golden snapshot.** Each job runs in a microVM restored from a golden snapshot, not in a shared container or straight on the host.
- **Tag routing.** A job can carry required_tags. A runner claims it only if the runner's own tags cover all of them, so a job lands on a host that can build it.
- **Streamed logs with secret masking.** Output streams back while the job runs. Secrets passed to the job are replaced with *** before the log is forwarded.
- **Time limits and cancel.** Every job has a timeout. The consumer can cancel a run, and the runner kills the microVM, not only the process inside it.
- **Separate tokens for consumers and runners.** A product that submits jobs and a host that runs them authenticate with different tokens. Neither can use the other's endpoints or read the other's data.

## Use cases

### AI agent sandboxes
Give an agent a machine it can wreck without touching yours.

- A task gets a fresh microVM that is destroyed when it ends.
- An agent that needs memory between prompts can have a persistent VM with its own disk. It is parked to a snapshot when idle and woken on the next prompt.
- Network access is off unless you name the hosts. Egress is a per-job allowlist.

### CI/CD
Run pipelines on hardware you control, one clean VM per job.

- Each job restores a fresh microVM, runs once, and the VM is destroyed afterwards.
- The runner host clones the repository and hands the job a git bundle, so the repository credential never enters the VM.
- A deploy job can carry secrets and a narrow egress allowlist, such as the API host only.

## How it works

1. **Submit.** Your product submits a job to the smbCloud API with its consumer token: a script, environment, timeout and any required_tags.
2. **Claim.** A runner whose tags match polls the queue and claims the oldest matching job.
3. **Restore a microVM.** The runner restores a Firecracker microVM from the golden snapshot and sends in the job, with the repository as a git bundle if there is one.
4. **Stream logs.** Output is streamed back as the job runs, with secrets masked.
5. **Report.** The runner reports success, failure, timeout or cancel, and destroys the VM.

## Security

- **Egress is closed by default.** A job has no network access unless it names hosts. Allowed traffic is HTTPS CONNECT on port 443 to those hosts only.
- **Credentials stay out of the VM.** The runner host does the git clone with a short-lived, read-only credential, then sends the code in as a git bundle. The VM never sees the credential.
- **A VM per job, then gone.** Ephemeral jobs run in a microVM that is destroyed after the job. A runner dies with its job, not the other way round.
- **Two token types.** Runners and consumers use separate tokens, stored as digests. A runner token cannot submit jobs and a consumer token cannot claim them.

## Built on

- Firecracker: microVMs restored from a golden snapshot
- smbcloud-runner: the runner, written in Rust
- smbCloud API: the queue, claim, log and cancel control plane

## Running today

- [siGit.si](https://sigit.si): CI/CD for repositories hosted on siGit.si.
- [Onde Onde](https://ondeinference.com/): Sandboxes for its agents.

## FAQ

### What is smbCloud Run?
smbCloud Run is a job-execution service from smbCloud. A product submits a job, a runner claims it and runs it in a Firecracker microVM, and the logs and result are reported back. It is used for AI agent sandboxes and for CI/CD.

### Is smbCloud Run available?
It is in early access. It already runs siGit.si CI/CD and Onde Onde's agents. To use it for your own workloads, email support@smbcloud.xyz to request access.

### How is Run different from GitHub Actions self-hosted runners?
Actions self-hosted jobs run directly on your host, as a user on that machine. Run executes each job in a Firecracker microVM that is destroyed afterwards, and it ships its own queue, tag routing, cancel and log streaming. Runners still pull, so both work behind NAT.

### Can an AI agent keep state between prompts?
Yes. A persistent VM has its own disk. When it is idle it is parked to a snapshot, and the next prompt wakes it. Task jobs that don't need state use a fresh VM instead.

### Does my repository's credential enter the VM?
No. The runner host clones the repository with a short-lived, read-only credential and sends the code into the VM as a git bundle. The credential stays on the host.

### Can a job reach the internet?
Only if you allow it. Each job carries its own egress allowlist: HTTPS CONNECT on port 443 to the hosts you name. With no allowlist there is no network access.

### Do runners need a public IP or open ports?
No. Runners poll smbCloud for work, and the server never connects to them. A runner behind home NAT works without port forwarding.

### Are secrets visible in the logs?
Secrets passed to a job are masked as *** in the log the runner forwards. They are encrypted at rest and cleared once the job finishes.

## Contact

Request early access: support@smbcloud.xyz

## Links

- Page: https://smbcloud.xyz/run
- Home: https://smbcloud.xyz/
- llms.txt: https://smbcloud.xyz/llms.txt