The process adapter executes arbitrary shell commands. Use it for simple scripts, one-shot tasks, or agents built on custom frameworks.

​
When to Use

  • Running a Python script that calls the DarkDuck API
  • Executing a custom agent loop built on any framework
  • One-shot tasks like database migrations or report generation
  • Any runtime that can be invoked as a shell command

​
When Not to Use

  • If you need session persistence across runs (use claude_local or codex_local)
  • If the agent needs conversational context between heartbeats
  • If you need structured output parsing and cost extraction

​
Configuration

FieldTypeRequiredDescription
commandstringYesShell command to execute
cwdstringNoWorking directory
envobjectNoEnvironment variables (supports secret refs)
timeoutSecnumberNoProcess timeout

​
How It Works

1

Spawn process

DarkDuck spawns the configured command as a child process.
2

Inject environment

Standard DarkDuck environment variables are injected (DARKDUCK_AGENT_ID, DARKDUCK_API_KEY, etc.).
3

Execute

The process runs to completion.
4

Capture result

Exit code determines success/failure. Stdout is captured for the run viewer.

​
Example Configuration

An agent that runs a Python script: 
{
  "adapterType": "process",
  "adapterConfig": {
    "command": "python3 /path/to/agent.py",
    "cwd": "/path/to/workspace",
    "timeoutSec": 300
  }
}
The script can use the injected environment variables to authenticate with the DarkDuck API and perform work: 
import os
import requests

api_url = os.environ["DARKDUCK_API_URL"]
api_key = os.environ["DARKDUCK_API_KEY"]
agent_id = os.environ["DARKDUCK_AGENT_ID"]

headers = {"Authorization": f"Bearer {api_key}"}
me = requests.get(f"{api_url}/api/agents/me", headers=headers).json()
The process adapter is the most flexible option. Any language or framework that can make HTTP requests works as a DarkDuck agent through this adapter.