Ethos

Ethos is an early-stage personal AI runtime. It is intended to become the shared brain behind agents and the interfaces that use them.

The goal is broader than wrapping model inference: models, tools, workflows, hooks, personas, and interfaces should be able to work together around durable context.

Important

Ethos is in alpha. It is not ready for general use, breaking changes are expected, and stored data or protocol compatibility is not guaranteed yet.

Current state

The current repository is foundational. It contains an in-progress agent loop and enough provider, session, workspace, persona, capability, CLI, and REST support to build and exercise that loop. These pieces are infrastructure, not the finished product or its defining feature set.

Ethos can currently connect to OpenAI, Google, or Ollama models and run locally through its CLI or Vox REST interface. The implementation is still changing quickly as the core runtime takes shape.

Try it

Ethos currently requires Python 3.12 or 3.13 and uv.

git clone https://github.com/Downmoto/ethos.git
cd ethos
uv sync

uv run ethos init
uv run ethos onboard
uv run ethos ask "Hello"

ask starts a fresh session and prints its ID with the response. Run uv run ethos --help to see the available workspace, persona, provider, capability, session, and server commands.

To run the Vox API:

uv run ethos start

Configuration and data

Ethos keeps its configuration, workspaces, sessions, skills, and local event data under ~/.ethos. Provider and runtime settings live in ~/.ethos/config.yaml; global capability settings and sparse workspace overrides live in ~/.ethos/capabilities.yaml. Personas, the global default for new workspaces, and workspace assignments live in ~/.ethos/personas.yaml.

For example, these commands lower the global skill limit, then disable skills and lower the resource limit in one workspace:

uv run ethos config capability set skills max_skills 50
uv run ethos config capability set skills enabled false \
  -f max_resources 100 --workspace my-project

Provider configuration can be inspected, checked without saving, and updated through the same CLI:

uv run ethos config provider show
uv run ethos config provider check model_name gpt-5-mini
uv run ethos config provider set name openai \
  -f model_name gpt-5-mini -f api_key ...

Provider output reports only whether a credential is configured. Credentials may instead be referenced through variables such as ETHOS_KEYS__OPENAI_API_KEY.

Personas are assigned to workspaces rather than individual sessions:

uv run ethos persona create reviewer name Reviewer \
  -f instructions "Review changes carefully." \
  -f capabilities '["skills", "file_system"]'
uv run ethos workspace persona my-project reviewer

Every session in my-project uses that assignment on its next turn. Disabled or removed assignments visibly fall back to the built-in ethos persona.

Application state is stored locally, but model requests are sent to the provider you select. Session history can contain reasoning, tool arguments, tool results, and file contents, so treat it as sensitive data.

Model evaluations

Ethos includes opt-in model evaluations that measure how effectively and securely different models use the real agent harness. They are separate from the ordinary test suite and produce raw results, detailed Markdown reports, and the overall leaderboard below.

See the evaluation documentation for scoring, suite formats, model configuration, and run instructions.

Direction

The immediate work is still completing personalisation and refining the agent loop. The broader roadmap includes workflows, hooks, and the systems needed to compose them without turning Ethos into a collection of unrelated features.

That direction will become more concrete as the underlying contracts settle.

Development

Contributor architecture and runtime contracts live in the developer documentation.

./scripts/verify.sh