Self-Hosted Agent (Docker)

Run the whole agent — model calls, loop and tools — inside a local Docker container you own

Run the whole agent — model calls, loop and tools — inside a local Docker container you own.

Quick Start

1. Minimal

   One line moves the whole agent into a container.

   from praisonaiagents import Agent
   
   agent = Agent(
       name="builder",
       instructions="You build things.",
       run_on="docker",
   )
   agent.start("Write a Python script that prints the first 10 primes, then run it")

2. With a prebuilt image

   Supply your own image with praisonaiagents baked in to skip the ~1 min first-run install.

   from praisonai import HostedAgent, HostedAgentConfig
   from praisonaiagents import Agent
   
   hosted = HostedAgent(
       provider="docker",
       config=HostedAgentConfig(model="gpt-4o-mini", system="Be brief."),
       image="my-org/praisonai-agent:latest",
   )
   agent = Agent(name="builder", backend=hosted)
   agent.start("Summarise the README in three bullets")

3. Extra environment and packages

   Pass extra environment variables and packages, and disable container reuse.

   from praisonai import HostedAgent, HostedAgentConfig
   from praisonaiagents import Agent
   
   hosted = HostedAgent(
       provider="docker",
       config=HostedAgentConfig(model="gpt-4o-mini"),
       env={"MY_FLAG": "1"},
       pip_packages=["praisonaiagents", "httpx"],
       keep_alive=False,
   )
   agent = Agent(name="builder", backend=hosted)
   agent.start("Fetch example.com and count the words")

How It Works

The agent on your machine ships its serialisable config into the container, which rebuilds the agent, calls the LLM and runs the tools — then returns the answer.

The model API key travels into the container via -e KEY — the value is read from your host environment, never placed on the command line, so it never shows up in docker inspect or a process listing.

run_on="docker" vs tools_run_on="docker"

Both spellings name the same place. What differs is what crosses the boundary — the parameter name carries the scope.

The object reports which scope you chose:

>>> from praisonaiagents import Agent
>>> Agent(name="x", instructions="i", run_on="docker")
Agent(name='x', thinks_on='a Docker container', tools_run_on='a Docker container')

>>> Agent(name="x", instructions="i", tools_run_on="docker")
Agent(name='x', thinks_on='this machine', tools_run_on='a Docker container')

Which one do you want?

Configuration Options

Pass these to HostedAgent(provider="docker", ...).

Since PR #4077 the generic backend honours image= too, so HostedAgent(provider="docker", image="my-org/agent:latest") behaves the same across the compute-backed places.

Model keys forwarded automatically

These variables are forwarded into the container when set in your host environment, passed with -e KEY (value read from your env), so they never appear in docker inspect or a process listing:

OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, COHERE_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY, OPENAI_BASE_URL, OPENAI_API_BASE.

Limitations

Troubleshooting

When Docker is not running, run_on="docker" fails fast and points you at the daemon-free alternative:

RuntimeError: run_on='docker' cannot start: docker is not available on this machine.
  For docker, check the daemon is running (`docker info`).
  For a cloud place, check its credential is set.
  To keep the loop here and move only the tools, use tools_run_on='docker' instead.

Best Practices

Related