Choose the right tool
An agent can have a Host, several Centrals and plugins. 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.
Add credentials and packages
Use the credential picker to map an environment variable, such asGITHUB_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.
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.
- Kubernetes
- Swarm
Add the annotation to the top-level Pod or Deployment metadata:
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 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 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. For automated host-based exports, check thex-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.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.

