Skip to main content
A Central gives an agent a container with the command-line tools it needs. Each task that uses it gets its own temporary environment, without requiring a Host.

​
Choose the right tool

An agent can have a Host, several Centrals and plugins. An agent that uses a Central can also use an HTTP API plugin. Describe each Central’s purpose so that the task can choose an appropriate command environment. The tool selection guide explains when plugins fit better than shell commands.
Central is off by default. Ask your installation administrator to enable it through Feature toggles and prepare the execution environment. Administrators create configurations, activate versions and run checks. Users and auditors can inspect configurations and results in organizations they can access.

​
Create a configuration

1

Open Central

Choose Add Central and enter a name and description, such as Cloud operations and Tools for the production cloud account.
2

Start from an example

Choose Kubernetes example or Swarm example, or import your YAML or JSON manifest.
3

Choose your image

Use an image containing the required tools, pinned to its immutable SHA-256 digest.
4

Validate the draft

Choose Validate and correct any errors reported in the editor.
5

Save the first version

Choose Create Central. Saving does not start a container or test its tools.
The manifest supports one Kubernetes Pod, one Kubernetes Deployment template or one Compose service. Keep the example’s schema declaration and security settings. Multiple containers, custom startup commands, volumes and privileged settings are not supported. Validation checks the configuration format. It does not check registry access, image compatibility or whether commands can run. A manifest must fit within 64 KiB of UTF-8. Keep large scripts and tool files in the container image. The examples request 0.1 CPU core and limit usage to 1 core. Memory requests are 128 MiB and limits are 256 MiB (128Mi/256Mi on Kubernetes, 128M/256M on Swarm). They run as UID/GID 1000, use a read-only root filesystem and drop all Linux capabilities. Keep these controls when adapting an example.

​
Add credentials and packages

Use the credential picker to map an environment variable, such as GITHUB_TOKEN, to a saved Secret or Vault path, then choose Add mapping. The manifest keeps a reference to the credential, not its value. Do not paste tokens into the manifest. For Swarm, the mapping has this shape:
2501 resolves credentials at the task’s first Central call and checks access again before delivering them to the container. Revocation blocks delivery. Credential values are redacted from command output. An image can already contain all its tools. Alternatively, declare exact package versions in the manifest; Additional packages shows those in the selected version. Packages are installed into temporary storage before task credentials arrive. No new image is published. The image must already contain the matching package manager. Use a prepared image for tools that need installation scripts or system services. Merge the matching fragment into your existing manifest, preserving its image and security settings. This example installs a Python package; choose the exact package and version your tools require.
Add the annotation to the top-level Pod or Deployment metadata:
Choose Validate, save the version and test it below. For manifests maintained outside the editor, use x-2501.credentials on the Compose service, or the JSON 2501.ai/credentials annotation on Kubernetes metadata. Map each environment name to {credential: <credential ID>}. An entire environment value can also be {secrets.github} or {secrets:github}. These names select the organization credential first, then a tenant credential only when no organization credential exists. A failed organization credential does not fall back. Partial string interpolation is unsupported. Dependencies support system, npm and python lists, each with package and an exact version. System packages need apk, or apt-get and dpkg-deb; npm packages need npm; Python packages need Python and pip. Installation scripts do not run, and Python packages require compatible wheels. Transitive dependencies resolve again when each container starts. Use a prepared image when you need reproducible dependencies, source builds or install scripts, and provide access to the required package repositories.

​
Test and activate a saved version

1

Select the version

Choose a Saved version in the action bar. Unsaved manifest edits are not part of the test.
2

Choose where commands run

Leave Cluster (optional) at No cluster (default) for local execution, or select a configured cluster in the organization.
3

Activate the settings

Choose Save settings to use the selected configuration for new tasks.
4

Run the check

In Dry run, choose Test to test commands in a temporary container and check that it is removed afterwards.
The installation supplies the command runtime automatically. You do not need to enter another runtime image. The test uses no task credentials. Changing the selected configuration invalidates the previous result. A disabled test explains what is missing. Deployment requirements are separate: Kubernetes and Docker Swarm. To use another namespace in the Engine’s Kubernetes cluster, declare it in the manifest:
To select an explicit Kubernetes namespace, set top-level metadata.namespace in a Pod or Deployment, or x-2501.namespace on a Compose service. Outside the configured shared namespace and engine namespace, it needs matching 2501.ai/tenant-id and 2501.ai/org-id labels, pod-security.kubernetes.io/enforce=restricted, and namespace-read and pod-management permissions. Remote Kubernetes Centrals use verified HTTPS dialback: configure the connection’s dialback_url or SATELLITE_DIALBACK_URL on the engine, plus certificate trust and network access. They do not use local pods/attach access. Deploy the engine’s multi-architecture image index when Central workloads use a different architecture from the engine. New bundled-runtime sessions resolve the current engine release when they launch; an existing container keeps its runtime, and an explicit runtime-image selection stays pinned. No CENTRAL_RUNTIME_IMAGE setting is needed. A dry run returning 409 central_runtime_unavailable means the bundled runtime could not be resolved; check the engine image and registry access.

​
Assign agents

Create agents from Agents and select their Centrals. Assign to Central adds an existing agent without removing its other Central assignments. Host-based CSV and JSON exports exclude Central-only agents; manage these assignments in Command Center. A task starts its Central container when it first needs it, then reuses that container. Its selected environment remains fixed for the task, including continuations. Configuration changes apply to new tasks. Create a new task when changing an existing task’s command environment. A queued or resumed task fails if its agent’s execution target has changed. If the change occurs during job planning, 2501 refuses the planned task and plans the job again. Start a new task for the new target. A task stops if none of the assigned Centrals fits its work. Removing every Central from an agent preserves its Host assignment. With both a Host and Centrals assigned, a task waits for the Host before selecting its environment. It reserves the Host until the task ends. For automated host-based exports, check the x-export-skipped-rows response header for excluded Central-only agents.

​
Keep versions and resolve failures

Save Changes creates a new version while preserving earlier versions. Compare with shows an older version alongside the editor. Export downloads the current editor content. If another administrator saved first, reload the saved version before trying again.
If a command’s outcome is unknown, check its effect before trying again. If container termination is unconfirmed, inspect the workload before recording termination evidence in Maintenance.

​
Execution limits

Output limits measure raw output. Interactive terminals and background jobs are unavailable in Central. Use a Host when the workflow needs those capabilities.