Jenkins Ephemeral Build Agents on CreateOS Sandbox: Setup Tutorial

Jenkins Ephemeral Build Agents on CreateOS Sandbox: Setup Tutorial

To get Jenkins ephemeral build agents on CreateOS Sandbox, install the plugin, store a CreateOS API key, build one agent template that contains a JVM, then add a cloud and a Sandbox Template with a label. Every Pipeline that asks for that label runs on a fresh microVM with its own guest kernel. By default, the agent and its sandbox are deleted when the build ends.

The CreateOS Sandbox plugin is an official Jenkins plugin. It is listed on the Jenkins plugin index, hosted under the jenkinsci organisation and maintained by CreateOS. This guide is for the Jenkins administrator or platform engineer who sets it up. For what shipped and why, read the launch announcement.

Key takeaways

• The CreateOS Sandbox plugin gives each Jenkins build its own one-executor microVM agent, deleted after that build by default.
• Stock CreateOS root filesystems such as devbox:1 have no JVM, so the Jenkins agent will not start until you build a template from the plugin's Dockerfile.agent.
• Inbound WebSocket, the default launch method, needs a Jenkins URL the sandbox can reach; localhost is the most common cause of a launch timeout.
• Outbound network access from a CreateOS sandbox is open until an egress rule is set, and the plugin's Sandbox Template has no egress field.
• The plugin needs Jenkins 2.541.3 or newer and a CreateOS API key.

What do you need before you start?

• Jenkins 2.541.3 or newer.
• A CreateOS account and API key, created in the CreateOS app.
• The CreateOS CLI, for step 3.
• Room in your plan for one custom template, plus one disk if you use the cache example in step 6. Some plans allow neither; the Limits page lists each plan's template and disk caps.
• For the default WebSocket launch, a Jenkins URL the sandbox can reach.

For background, read the Sandbox overview.

Step 1: How do I install the CreateOS Sandbox plugin?

Install it from Manage Jenkins > Plugins > Available plugins, or with the plugin installation manager:

jenkins-plugin-cli --plugins createos-sandbox

Versions look like 24.vfe318c36a_db_8 because releases ship through the Jenkins project's continuous delivery pipeline.

Step 2: How do I add the CreateOS API key to Jenkins?

Go to Manage Jenkins > Credentials and add a "Secret text" credential that holds the key. The cloud in step 4 points at it, so the key stays in Jenkins Credentials.

Step 3: How do I build a Jenkins agent template with a JVM?

Build it from Dockerfile.agent in the plugin repository. The stock images devbox:1, debian:13, ubuntu:26.04 and alpine:3.20 ship no JVM, so agent.jar downloads and then fails to start.

git clone https://github.com/jenkinsci/createos-sandbox-plugin
cd createos-sandbox-plugin
createos template submit --name jenkins-agent-jdk25 --dockerfile Dockerfile.agent
createos template list   # wait for status: ready

The image carries a checksum-pinned Temurin JDK 25, a pinned agent.jar, git, Node.js, disk-mount tools and /home/jenkins.

• Java version. Under the Jenkins Java support policy, agents on LTS 2.555.1 and later must run Java 21 or 25.
• Naming. Name templates per JDK (jenkins-agent-jdk25, jenkins-agent-jdk21) so several can coexist.
• Rebuilds. Rebuilding a name deletes and resubmits it, and launches that use it fail meanwhile. Rebuild when the queue is quiet.

Step 4: How do I add the CreateOS cloud and a Sandbox Template?

Go to Manage Jenkins > Clouds > New cloud and select "CreateOS Sandbox".

Then add a Sandbox Template:

Give the built-in node zero executors. Otherwise a build can land in the controller's JVM, where JENKINS_HOME and the API credential live.

Step 5: Should I use Inbound WebSocket or SSH over a CreateOS tunnel?

Use WebSocket when the sandbox can reach your Jenkins URL over HTTPS. Use SSH when the controller must open the connection.

• WebSocket: set Manage Jenkins > System > Jenkins URL to an address the sandbox can reach, never localhost.
• SSH: select a Jenkins SSH private-key credential in the template's SSH Credentials field. Its username must exist in the root filesystem; Dockerfile.agent provides jenkins.

Step 6: How do I run a Declarative Pipeline on a CreateOS agent?

Request the template's label. This is the README's minimal Pipeline:

pipeline {
    agent { label 'createos' }
    stages {
        stage('Build') {
            steps {
                echo 'Hello from CreateOS Sandbox'
                sh 'uname -a'
            }
        }
    }
}

Do not use agent any: CreateOS agents accept only jobs that name their label.

To change settings for one Pipeline, use agent { createos inheritFrom: ... }. This README example mounts a Maven cache disk:

pipeline {
    agent {
        createos inheritFrom: 'createos',
                 disks: [[id: 'my-maven-cache', mountPath: '/mnt/cache/maven']]
    }

    stages {
        stage('Build') {
            steps {
                sh 'mvn -B -Dmaven.repo.local=/mnt/cache/maven clean package'
            }
        }
    }
}

Overrides apply only when the template allows them.

Step 7: How do I check that the agent was deleted after the build?

Open the Jenkins node list after the build: the CreateOS agent that ran it is gone. By default the agent takes one build and is deleted with its sandbox when that build succeeds, fails or aborts. If one stays, check whether reuse is on.

The workspace goes with the sandbox, so keep outputs with archiveArtifacts:

node('createos') {
    sh './build.sh'
    archiveArtifacts artifacts: 'build/**'
}

Why does my CreateOS agent not come online?

Most failures come from a localhost Jenkins URL or a root filesystem with no JVM.

• WebSocket launch times out. The Jenkins URL is localhost, which a sandbox microVM cannot reach.
• agent.jar downloads, then fails to start. The template uses a stock image. Point Root Filesystem at your JVM template.
• The job waits in the queue. It uses agent any or a label no template carries.
• SSH authentication fails. The credential username does not exist in the root filesystem.

What should you know before running this in your Jenkins?

• Billing during downtime. Sandboxes keep running, and billing, while the controller is down, so builds can resume. A controller deleted outright leaves its sandboxes to remove by hand.
• Reuse costs idle time. With reuse on, an agent bills while idle until its timeout.
• Outbound is open by default. The Sandbox Template has no egress field. Set an allowlist on the sandbox through the CreateOS API or CLI; see Egress rules.
• Your plan caps concurrency. The Limits page lists each plan's concurrent sandboxes, so Container Cap can be set higher than your plan allows.
• Each sh adds overhead. Group related commands into one block.

When you do not need this: if your builds run only code your team wrote and reviewed, and a warm static agent serves them well, a new VM per build adds launch work for little gain. It pays off for untrusted or agent-written code; see Firecracker sandboxes for AI agents and when coding agents need Firecracker.

Common questions

How do I give every Jenkins build its own fresh agent?

Use a cloud plugin that provisions one agent per build. With the CreateOS Sandbox plugin, each queued build gets its own one-executor microVM, up to the container cap. By default the agent is deleted with its sandbox when the build ends.

Which Java version does a Jenkins agent template need?

Agents follow the same Jenkins Java support policy as the controller. From LTS 2.555.1, agents must run Java 21 or 25. The plugin's Dockerfile.agent ships Temurin 25.

Can I keep a Maven or npm cache between ephemeral Jenkins agents?

Yes. Attach a CreateOS disk through the template or inheritFrom and point Maven's local repository at it. For Node, keep npm install in the workspace and store only a compressed node_modules tarball on the disk.

Can I reuse one CreateOS agent across several Jenkins builds?

Yes, by turning on Reuse agent between builds. The agent then stays up for further builds, and its sandbox keeps billing while idle until the idle timeout deletes it.

What happens to running builds when the Jenkins controller restarts?

By default the sandboxes keep running, agents reconnect, and running sh steps resume. With Delete agents on controller restart enabled, agents are deleted on startup and running builds fail.

How do I restrict outbound network access from a Jenkins microVM agent?

Set an egress allowlist on the sandbox through the CreateOS API or CLI. Outbound is open until a rule is set; once any rule exists, only listed destinations pass. The plugin's Sandbox Template has no egress field.

Where do I install the plugin?

Install CreateOS Sandbox from the Jenkins plugin index, then follow steps 2 to 7 above.

About CreateOS

CreateOS runs AI agents and the code they write. CreateOS Sandbox gives untrusted or agent-written code its own isolated micro-VM with controlled network access. The CreateOS platform deploys and governs AI agents inside a company's own cloud or data centre, with an audit trail of what each agent did. Start at createos.sh.