Skip to content

Getting Started

Pygent is a minimalist coding assistant that runs shell commands inside a sandboxed environment. By default a Docker container is used, but if Docker is unavailable the commands run locally instead. This page shows how to install the package and gives a few examples covering the main features.

Installation

The recommended way to install Pygent is using pip:

pip install pygent

To include optional features like Docker support or the web UI, you can specify extras:

pip install pygent[docker,ui]

Python 3.9 or newer is required. If Docker is not installed on your system, you should omit the [docker] extra; commands that would use Docker will then run on the host system instead. Docker itself needs to be installed separately if you wish to use containerized execution.

For developers or those wanting the latest unreleased features, Pygent can also be installed from source:

pip install -e .
You can include extras like [docker,ui] when installing from source as well (e.g., pip install -e .[docker,ui]).

Interactive session

Start an interactive session by running pygent in a terminal. Use the --docker flag to force container execution or --no-docker to run locally. The CLI prints the persona name and whether commands run local or in Docker when the session starts so you know which agent is active. At the beginning of each request, the assistant proposes a short plan for how it intends to solve the task and waits for your approval before executing any commands. This helps you keep control over the session.

$ pygent --docker
vc> echo "Hello"

Each message is executed in the sandbox and the output printed. Use /exit to leave the session. You can also launch a simple web interface with pygent ui (or the old pygent-ui script, requires the ui extra).

Use /help inside the CLI to list available commands or /help <cmd> for details. The helper shows /cmd to run a raw shell command, /cp to copy files into the workspace and /new to restart the conversation while keeping the current runtime. Use /tools to enable or disable specific tools on the fly. Pass --no-confirm-bash if you want to skip the default confirmation before running any bash command. When confirmation is enabled, the agent displays the command before asking for approval. You can toggle this behaviour at runtime with /confirm-bash on|off. Add --ban-cmd NAME to prevent certain commands entirely. The /save DIR command copies the workspace, the CLI log and relevant configuration for later use. Resume the session with pygent --load DIR. Use /banned inside the CLI to list or modify the banned commands.

Tool usage

During the conversation the assistant can call several built-in tools. bash runs shell commands and write_file creates files inside the workspace. For example:

vc> write_file path="hello.txt" content="Hello from Pygent"
vc> bash cmd="cat hello.txt"

You can disable all built-in tools with pygent.clear_tools() or remove a specific one with pygent.remove_tool("bash"). Restore the defaults at any time using pygent.reset_tools(). The system prompt will update automatically to list the tools currently registered.

Using the API

The same functionality is accessible programmatically via the Agent class:

from pygent import Agent

ag = Agent()
ag.step("echo 'Hello World'")
ag.runtime.cleanup()

See api_example.py for a complete script. Additional examples show how to implement a custom model and how to interact with the Runtime class directly.

Configuration

Pygent communicates with the model through an OpenAI‑compatible API. Export your API key before running the assistant. A full list of environment variables is available in the Configuration page.

For full control you may pass a custom model implementation to Agent. The file custom_model.py contains a minimal echo model example. A dedicated Custom Models page expands on this topic with additional scenarios.

Additional examples

Several scripts in the examples/ directory showcase different parts of the package (see the dedicated Examples page):

  • api_example.py – minimal use of the :class:~pygent.agent.Agent API.
  • runtime_example.py – running commands through the :class:~pygent.runtime.Runtime class directly.
  • write_file_demo.py – calling the built-in tools from Python code.
  • custom_model.py – plugging in a custom model.

Below is the custom model snippet for reference:

from pygent import Agent, openai_compat

class EchoModel:
    def chat(self, messages, model, tools):
        last = messages[-1]["content"]
        return openai_compat.Message(role="assistant", content=f"Echo: {last}")

ag = Agent(model=EchoModel())
ag.step("test")
ag.runtime.cleanup()

Custom models can also issue tool calls. The following model runs the last user message as a bash command:

import json
from pygent import Agent, openai_compat


class BashModel:
    def chat(self, messages, model, tools):
        cmd = messages[-1]["content"]
        call = openai_compat.ToolCall(
            id="1",
            type="function",
            function=openai_compat.ToolCallFunction(
                name="bash",
                arguments=json.dumps({"cmd": cmd}),
            ),
        )
        return openai_compat.Message(role="assistant", content=None, tool_calls=[call])


ag = Agent(model=BashModel())
ag.step("echo hi")
ag.runtime.cleanup()

See the API reference for the complete list of classes and configuration options.