Installation

Enso 0.1.0 is currently an unreleased, pre-production project. There is no public package or working public source repository yet, so there is no supported public install command. In particular, Enso does not publish an install.sh script.

If you already have an authorized Enso source checkout, the steps below describe the current source installation. Otherwise, use this documentation to evaluate Enso and wait for a public distribution before trying to install it.

Requirements

An Enso machine needs:

• macOS or Linux. The background-service integration uses launchd or systemd.
• Python 3.14. The package declares requires-python = ">=3.14".
• uv. Enso is currently installed as a uv tool from a source checkout.
• At least one supported agent CLI: claude, codex, or grok, already installed and authenticated for the account you intend to use.
• At least one chat transport: a Slack app using Socket Mode or a Telegram bot token.

Enso drives provider CLIs; it does not install them, log into them, or replace their credentials. Before starting setup, confirm at least one provider works in your terminal:

command -v claude
command -v codex
command -v grok

Only one needs to be present. Run that CLI’s own harmless help or status command if you are unsure whether its authentication is current.

Install from a source checkout

From the root of an authorized Enso checkout, install the transports and optional viewer you need:

cd /path/to/enso
uv tool install -e '.[slack,telegram,web]'

The extras are independent:

Install only what you use. For example, a Telegram-only host without the viewer can use:

uv tool install -e '.[telegram]'

The base CLI still includes enso web status and enso web stop without the web extra. enso web start explains which extra is missing instead of failing with an import traceback.

Confirm the executable is available:

command -v enso
enso --help

If the first command prints nothing, ensure uv’s tool executable directory is on PATH. Use uv’s own environment guidance for your shell rather than hard-coding a path from another machine.

Prepare a transport

Setup connects one transport. You can add the second later in config.json.

Slack preparation

Slack requires both a bot token and an app-level token with Socket Mode enabled. The authorized source checkout includes assets/slack/manifest.json, which declares the exact scopes and events Enso needs.

Before running setup:

1. Create a Slack app from that manifest.
2. Enable or confirm Socket Mode.
3. Keep the bot token (xoxb-…) and app-level token (xapp-…) available.
4. Decide which channel or direct message should receive the setup test.
5. Invite the bot to every channel you later bind.

When applying the manifest to an existing app that has broader scopes, revoke the old bot token before reinstalling the app. Slack does not remove old scopes from a live token. A reinstall also removes the bot from channels, so invite it again afterward.

Telegram preparation

Telegram uses one bot token and an allowlist of numeric user ids. Setup waits for you to send the bot a private message, then records the sender’s numeric id.

Enso accepts Telegram private chats only. Users not listed in allowed_users are ignored silently, so make sure the account you use during setup is the account you intend to allow.

Run guided setup

Use your real Enso home only when you are ready to create persistent configuration:

enso setup

On a fresh home, the wizard proceeds in order:

1. Detects supported provider CLIs on PATH and records their available model choices and unattended permission flags.
2. Asks for the default provider, model, and effort.
3. Connects one Slack or Telegram transport. Slack validates the bot token; Telegram waits for a private message so it can capture the user’s numeric id.
4. Creates the default workspace and seeds the home instructions, bundled skills, discovery links, and empty Git root.
5. Writes config.json, sends a test when a notification destination is configured, and offers to install the background service.

The wizard is intended for a fresh home. If setup reports existing or invalid state, stop and inspect it instead of repeatedly overwriting files. Enso’s configuration and workspace audit commands collect problems without requiring you to guess which file is wrong.

What setup creates

The important initial paths are:

~/.enso/
├── config.json
├── AGENTS.md
├── CLAUDE.md -> AGENTS.md
├── skills/
├── workspaces/default/
│   ├── AGENTS.md
│   ├── knowledge/
│   ├── drafts/
│   ├── uploads/
│   └── skills/
├── jobs/
├── secrets/
└── .git/

See Workspaces before changing this layout manually. The links and Git root are part of provider instruction and skill discovery, not incidental scaffolding.

Install and operate the service

If you did not install the service during setup, do it explicitly:

enso service install
enso service status

The service command supports the full lifecycle:

enso service start
enso service stop
enso service restart
enso service status
enso service uninstall

service install writes a user service for the particular enso executable on your current PATH, then starts it. The unit is stored at:

• ~/Library/LaunchAgents/com.enso.agent.plist on macOS;
• ~/.config/systemd/user/enso.service on Linux.

The generated service environment includes a PATH that covers every configured provider. If you later move or reinstall a provider or Enso itself, enso doctor warns when the service unit and current executable no longer agree.

Restart the service after editing config.json; transports, providers, bindings, and workspace overrides load at process start. JOB.md files are different: the scheduler reloads them every minute, so job edits need no service restart.

Verify the installation

Run the checks from narrowest to broadest:

enso config check
enso workspace audit
enso doctor
enso service status

• config check validates strict JSON and reports every configuration problem it can find.
• workspace audit checks the Enso home, fixed directory layout, instruction links, skill links, collisions, bindings, and jobs.
• doctor combines those checks with provider paths, transport extras, service state, and all job definitions.
• service status confirms whether the installed user service is actually running.

Then test the transport:

• Send !help in a bound Slack conversation.
• Send /help in a bound Telegram private chat.

Use !status or /status to see the effective workspace and agent, where the agent choice came from, the current session age, active work, and queue depth.

Read logs without exposing too much

The main rotating log is ~/.enso/enso.log:

enso logs -n 100
enso logs -f
enso logs --job morning-brief
enso logs --turn a1b2c3
enso logs --grep timeout

On macOS, service stdout and stderr also go to ~/.enso/launchd.log; this is mainly useful when the process crashes before normal logging starts.

Avoid enso serve --debug on a shared or poorly protected machine. Debug mode records complete prompts and raw provider events, which can include private chat content, file paths, tool output, and secrets exposed by a provider.

Start the optional viewer

With the web extra installed:

enso web start
enso web status

The default URL is http://127.0.0.1:8787. The viewer runs separately from the service, writes to ~/.enso/web.log, and does not survive a reboot. It is read-only and has no authentication, so keep it on localhost unless a trusted private tunnel or authenticated reverse proxy controls access.

Stop it independently:

enso web stop

See Web viewer for its pages and threat model.

Add the second transport or more workspaces

The first-run wizard connects one transport and creates default. Further setup is file-based:

1. Create another workspace with enso workspace create NAME.
2. Add the second transport and any bindings to ~/.enso/config.json.
3. Run enso config check and enso workspace audit.
4. Restart the service.
5. Send status in the newly bound conversation to confirm the route.

Follow Configuration for strict copyable examples and Workspaces before editing workspace internals.

Upgrade a source installation

Enso is pre-production and provides no migration promise yet. When an authorized source checkout is updated:

1. Read its changelog and documentation before reinstalling.
2. Update the checkout using the method supplied by its distributor.
3. Repeat the same uv tool install -e '.[…]' command from the source root.
4. Run enso config check and enso workspace audit.
5. Fix every reported incompatibility.
6. Reinstall or restart the service if the Enso executable location changed.

Back up ~/.enso before testing a version that changes the config schema, database, or home layout.

Development and isolated evaluation

Contributors with a source checkout can create the development environment with:

uv sync --all-extras
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest

Always point manual development runs at a scratch home:

ENSO_HOME=/tmp/enso-dev uv run enso setup
ENSO_HOME=/tmp/enso-dev uv run enso serve --debug

That prevents development setup, config, jobs, sessions, and logs from touching the real ~/.enso home.

Installation troubleshooting

enso is not found

Confirm uv tool install succeeded, then add uv’s tool executable directory to your shell PATH. Start a new shell and retry command -v enso.

A provider is missing

Run command -v claude, command -v codex, or command -v grok in the same environment. If it works interactively but not as a service, run enso doctor and compare the provider path in config.json with the service’s recorded executable paths.

The service runs but chat is silent

Check, in order:

enso doctor
enso service status
enso logs -n 100

Then confirm the chat location has a binding, the named workspace exists, the Slack bot was invited to the channel or the Telegram user id is allowed, and the configured transport extra is installed.

Configuration changed but behavior did not

Run enso config check, then enso service restart. Configuration loads only when the service starts. Job files are the exception and reload on the scheduler’s next minute tick.