RedOS Runtime Agent

The RedOS runtime agent is a pull-based worker process. It authenticates with a worker token, claims WORKER_RUNTIME tasks, runs one non-interactive shell command at a time, streams output to the control plane, and reports final results.

The agent is packaged as a separate instance under agent/. Its runtime environment is intentionally separate from the control-plane .env.

PyPI Package

Package name:

redteam-os-agent

The package version is currently sourced from:

agent/redos_agent/__init__.py

If you update the code and want to publish again, you must bump redos_agent.__version__ first. PyPI will reject uploading the same version twice.

Boundaries

This agent does not install tools, create persistence, open an interactive terminal, run MCP, perform exploit automation, or choose commands by itself. It only executes task payloads explicitly created and dispatched by the control plane.

Configuration

Required:

cp agent/.env.example agent/.env

Then edit agent/.env and set at least:

REDOS_AGENT_API_URL="http://localhost:5000/api"
REDOS_AGENT_WORKER_TOKEN="rw_<worker_id>_<secret>"

Create A Worker Token

Create or reuse a worker through the operator API, then rotate a worker token:

curl -sS -X POST "http://localhost:5000/api/workers/$WORKER_ID/token" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"

The plaintext token is shown once. Store it in REDOS_AGENT_WORKER_TOKEN.

Run Locally

python -m venv .agent-venv
. .agent-venv/bin/activate
pip install -r agent/requirements.txt
set -a
. agent/.env
set +a
PYTHONPATH=agent python -m redos_agent

If installed from PyPI instead of source, run:

redteam-os-agent

Install As A Service

After installing from PyPI, you can install and start the agent as a systemd service with one command:

sudo redteam-os-agent-install

The installer will:

1. ask for the RedOS API URL
2. ask for the worker token
3. validate the token with the control plane by sending a heartbeat
4. if validation succeeds, write the service config
5. enable and start the service immediately

The installer writes:

• env file: /etc/redteam-os-agent/agent.env
• service file: /etc/systemd/system/redteam-os-agent.service

After install:

systemctl status redteam-os-agent
journalctl -u redteam-os-agent -f

If you prefer non-interactive install:

sudo redteam-os-agent-install \
  --api-url "http://localhost:5000/api" \
  --worker-token "rw_<worker_id>_<secret>" \
  --agent-name "redos-agent-service" \
  --yes

Run With Docker Compose

cp agent/.env.example agent/.env
# edit agent/.env
docker compose -f agent/docker-compose.agent.yml --env-file agent/.env up --build

On Linux, the compose file maps host.docker.internal to the host gateway. Because the compose file now lives under agent/, its Docker build context and env file are fully local to the agent instance.

Build And Publish To PyPI

First build

From the repository root:

python -m venv .publish-venv
. .publish-venv/bin/activate
python -m pip install --upgrade pip build twine
cd agent
python -m build
python -m twine check dist/*

This creates:

• dist/redteam_os_agent-<version>.tar.gz
• dist/redteam_os_agent-<version>-py3-none-any.whl

First upload

Upload to PyPI:

cd agent
python -m twine upload dist/*

If you want to test the package first, upload to TestPyPI:

cd agent
python -m twine upload --repository testpypi dist/*

Install after publish

pip install redteam-os-agent

Install and start as a service right after package install:

sudo redteam-os-agent-install

Rebuild and publish again after code changes

1. Update the code.
2. Bump agent/redos_agent/__version__.
3. Rebuild clean artifacts.
4. Upload the new version.

Recommended flow:

. .publish-venv/bin/activate
cd agent
rm -rf build dist *.egg-info
python -m build
python -m twine check dist/*
python -m twine upload dist/*

Verify published package

pip install --upgrade redteam-os-agent
redteam-os-agent

If you are testing against TestPyPI:

pip install --index-url https://test.pypi.org/simple/ redteam-os-agent

Dispatch A Runtime Task

Create a harmless task:

curl -sS -X POST "http://localhost:5000/api/tasks" \
  -H "Authorization: Bearer $REDOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"runtime-agent","command_payload":"whoami"}'

Dispatch it for worker-runtime mode:

curl -sS -X POST "http://localhost:5000/api/tasks/$TASK_ID/dispatch" \
  -H "Authorization: Bearer $REDOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"WORKER_RUNTIME"}'

The agent will claim the task, create a runtime TaskExecution, stream output, and finalize the task result.

To collect artifacts, include artifact_paths when creating the task:

curl -sS -X POST "http://localhost:5000/api/tasks" \
  -H "Authorization: Bearer $REDOS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"runtime-agent","command_payload":"printf hello > /tmp/redos-artifact.txt","artifact_paths":["/tmp/redos-artifact.txt"]}'

The agent uploads existing artifact files before reporting completion or failure. Missing files are reported as artifact metadata with status MISSING.

Observe Output

List executions:

curl -sS "http://localhost:5000/api/tasks/$TASK_ID/executions" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"

Watch live SSE output:

curl -N "http://localhost:5000/api/tasks/$TASK_ID/executions/$EXECUTION_ID/stream?last_id=0-0" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"

Read durable logs and final results:

curl -sS "http://localhost:5000/api/tasks/$TASK_ID/executions/$EXECUTION_ID/logs" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"

curl -sS "http://localhost:5000/api/tasks/$TASK_ID/results" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"

List and download artifacts:

curl -sS "http://localhost:5000/api/tasks/$TASK_ID/artifacts" \
  -H "Authorization: Bearer $REDOS_API_TOKEN"

curl -L "http://localhost:5000/api/tasks/$TASK_ID/artifacts/$ARTIFACT_ID/download" \
  -H "Authorization: Bearer $REDOS_API_TOKEN" \
  -o redos-artifact.bin