A local-first Python agent runtime built around deterministic workflows — predictable, repeatable, and yours to shape.

Arpels Agent is a Python-based personal agent runtime built around Google ADK. One local gateway, one durable agent, and a strong bias toward deterministic workflows over freeform LLM dispatch — the parts of your day that should always run the same way, run the same way.

It is for people who want to live inside their assistant rather than rent one, and who want the boring, repeatable parts to actually be boring and repeatable.

• Workflow-first — describe the steps that must happen, in order, with explicit inputs and outputs; the model fills in only the parts that genuinely need a model. Same input twice → same outcome twice.
• Google ADK at the core — the runtime builds and serves a real ADK agent, not a wrapped chat loop.
• Local-first by default — user state lives under ~/.arpels; nothing leaves your box you did not put there.
• Extensible without ceremony — drop toolsets, skills, and plugins onto the filesystem; they load.
• One control plane — CLI, gateway daemon, and FastAPI app all bind to the same runtime model.
• Automation built in — cron is a first-class part of the runtime, not an add-on.

Runtime: Python 3.12+ with uv.

git clone https://github.com/arpels/arpels-agent
cd arpels-agent
uv sync

Start the gateway with an explicit primary model:

uv run arpels gateway start \
  --models-primary-provider openai \
  --models-primary-model gpt-4o

Arpels will bootstrap ~/.arpels on first run and load:

• ~/.arpels/tools
• ~/.arpels/skills
• ~/.arpels/plugins
• ~/.arpels/crons

Check the gateway:

uv run arpels gateway status

If you want the ADK-backed FastAPI app without the gateway daemon:

ARPELS_MODELS_PRIMARY_PROVIDER=openai \
ARPELS_MODELS_PRIMARY_MODEL=gpt-4o \
uv run uvicorn arpels.api_server.app:app --host 127.0.0.1 --port 16600

Gateway status is exposed at:

GET /gateway/status

arpels/
  agent/        Agent construction and runner helpers
  api_server/   ADK FastAPI app bootstrap
  built_in/     Built-in tools
  cli/          Terminal commands (typer-based)
  cron/         Cron model and execution
  gateway/      Runtime loading, daemon, channel startup
  plugin/       Plugin loading and base APIs
  skills/       Skill loading and toolset assembly
  tools/        User toolset loading

uv run arpels --help

Main command groups:

• arpels onboard — guided first-run setup
• arpels gateway — daemon lifecycle
• arpels tools — manage user toolsets
• arpels skills — manage skills
• arpels plugins — manage plugins
• arpels cron — manage scheduled jobs
• arpels logs — tail runtime logs

uv run arpels tools list
uv run arpels skills list
uv run arpels plugins list
uv run arpels cron list

uv run arpels tools add notes --description "Project note helpers"

Creates ~/.arpels/tools/<name>/ with arpels.toolset.json and index.py. Export toolset from index.py and Arpels loads it into the agent.

uv run arpels skills add summarize --description "Summarize long text"

Arpels loads:

• ADK skill directories with SKILL.md / skill.md
• legacy Python skills exporting skill

Plugins live under ~/.arpels/plugins/<name>/. Each plugin defines arpels.plugin.json and index.py. A plugin can contribute:

• tools
• callbacks
• skills
• an optional long-running channel

uv run arpels cron add "health-check" "*/5 * * * *" "echo ok"
uv run arpels cron remove health-check

Out of the box:

• bash execution
• file read / write / directory listing
• HTTP fetch
• Python execution
• web search
• skill search and install
• cron job registration

User toolsets stack on top, so the base runtime stays small.

Ready-to-use plugins live under community/plugins/. Drop one into ~/.arpels/plugins/, fill in its configs block in arpels.json, restart the gateway.

To contribute one, see community/README.md.

Arpels reads config from ~/.arpels/arpels.json. The primary model is required and can be supplied via config, CLI flags, or environment variables:

• ARPELS_MODELS_PRIMARY_PROVIDER
• ARPELS_MODELS_PRIMARY_MODEL
• ARPELS_MODELS_PRIMARY_BASE_URL
• ARPELS_MODELS_PRIMARY_API_KEY

uv sync
uv run ruff check .

Local API work with reload:

ARPELS_MODELS_PRIMARY_PROVIDER=openai \
ARPELS_MODELS_PRIMARY_MODEL=gpt-4o \
uv run uvicorn arpels.api_server.app:app --reload

• Google ADK — the agent runtime foundation.
• LiteLLM — provider abstraction.
• Typer — CLI ergonomics.

Apache License 2.0 — see LICENSE.