Core concepts
The vocabulary behind the console and the API, covering workspaces, artifacts, runners, slots, CI executions and retention.
The console and the API use a small, consistent vocabulary. This page defines each term in one place so the guides can stay focused on their task.
Workspace
A workspace is the boundary for everything in SpawnDroid. It maps to an organisation and owns your artifacts, runners, API keys, members and sessions. Every request is scoped to a workspace, whether it arrives from the console through a signed in session or from a pipeline through an API key. You can belong to more than one workspace and switch between them at any time.
Artifact
An artifact is an uploaded Android build. Uploading decodes the manifest, extracts the icon and reads the package name, version name and version code. Builds are grouped by package name, so a new version of an existing package appends to the same artifact rather than creating a second one.
Version
Each artifact keeps a history of versions. The console always points at the highest version code, and the version selector lets you stream or install any retained release. Re uploading the same version code replaces that release in place. Uploaded builds are capped at 512 MB.
Runner
A runner is one Android device booted for a session. It is an isolated container with its own network, and it is destroyed when the session ends. A runner moves through a short set of states.
| State | Meaning |
|---|---|
booting | The device is starting and the framework is up |
installing | The build is being installed on the device |
ready | The app is installed and the runner is usable |
failed | The runner could not be prepared |
Session
A session is the durable record of a runner's lifetime. It stores which artifact ran, which device profile was used, when it started and ended, and the reported result for a CI run. Sessions are the history you see under Active Runners and Test Logs, and they are never deleted when an artifact is removed, because they form the workspace ledger.
Parallel slots
Parallel slots are the number of runners a workspace can have live at the same time. This is the limit that governs the product. On the Free plan you get one slot, so starting a second device while the first is still running returns a concurrency error and the console offers to stop the running session or add a slot. Time is not metered, so a slot being free is the only thing you need to watch.
CI execution
A CI execution is a runner started by a pipeline through the versioned API. It carries a WebDriver endpoint for Appium, reports a pass or fail result, and retains a logcat capture and a screen recording at teardown. CI executions appear in Test Logs alongside manual sessions.
Device profile
A device profile is one cell in the device matrix: an Android version combined with a form factor. SpawnDroid offers Android 12, 13 and 14 on a phone or a tablet screen, and the default is Android 14 on a phone. Pass a profile id when starting a runner to choose a different cell.
API key
An API key authenticates a pipeline or service. It carries a scope of full, upload or read, which SpawnDroid enforces on every request, and the secret is shown once at creation and stored only as a hash. Use the narrowest scope that does the job.
Retention
Retention is how long SpawnDroid keeps superseded builds and CI artifacts. On the Free plan, superseded versions older than 7 days are pruned, and stale logcat captures and recordings are cleared, but the newest release of every artifact is always kept so a shared link for the build in use never breaks. Paid tiers keep everything for 30 days. See Plans and limits for the exact windows.