Open-source agentic AI framework.

Before you begin

Zeline runs on Linux, macOS, Windows/WSL2, and Android through Termux. The official installer prepares Python, uv, the isolated environment, and launcher automatically.

Choose where Zeline will run

Use a phone for experimentation, a computer for daily work, or a VPS when the agent must stay online independently.

Budget VPS options

A VPS is optional, but it is the only way to keep a gateway, cron jobs, and webhooks online independently of your laptop or phone. Prices below are indicative entry tiers gathered from each provider — always confirm the current price, region, bandwidth cap, and terms of service on the provider site before buying.

Termux setup

Termux is the practical Android route for a portable Zeline installation. Install Termux from F-Droid or GitHub—not the outdated Play Store build—then keep the device awake while the gateway runs.

pkg update -y
pkg install git python -y
curl -fsSL https://zerolinear.com/install.sh | bash
zeline setup
termux-wake-lock

What works, what does not

Common Termux problems

Install Zeline Framework

The shell installer is the recommended path on Linux, macOS, WSL2, and Termux. Native Windows users can install the Python package from PowerShell.

curl -fsSL https://zerolinear.com/install.sh | bash
zeline setup
zeline doctor

pip install zeline-agent
zeline setup
zeline doctor

Set up an AI provider

Zeline is provider-agnostic. Pick a provider and model interactively, then manage API keys or OAuth credentials through the auth manager.

zeline model
zeline auth
zeline auth add openrouter
zeline auth list

Run your first chat

Validate the local agent before adding messaging platforms. A successful response confirms the model, provider, and credentials work together.

zeline chat -q "Introduce yourself in one sentence."
zeline sessions list

Configuration and tools

Use the CLI instead of manually guessing configuration keys. Secrets belong in ~/.zeline/.env; durable settings belong in ~/.zeline/config.yaml. Tool changes load on the next session.

zeline config
zeline config check
zeline config path
zeline config env-path
zeline tools list
zeline tools enable web

Sessions and project context

Zeline stores sessions in SQLite with searchable history. Resume, branch, rename, export, or prune conversations while keeping project rules separate from personality.

zeline sessions list
zeline sessions browse
zeline sessions export sessions.jsonl
zeline --continue

Free tiers and low-cost access

Provider limits change frequently. Treat every free tier as experimental, confirm current limits on the official site, and keep a fallback for important workloads.

Routers with free starting credit

These are third-party services, not official Zeline integrations. They expose OpenAI-compatible or Anthropic-compatible endpoints, so Zeline can use them as a custom provider. Free credit amounts and model catalogs change frequently — treat every number below as a starting point to verify on the provider dashboard.

Point Zeline at any OpenAI-compatible router

# 1. Register, create a key, and copy the exact base URL from the dashboard
# 2. Store the credentials, then select the model interactively
zeline config set OPENAI_BASE_URL https://api.example-router.ai/v1
zeline config set OPENAI_API_KEY sk-your-key
zeline model
zeline chat -q "Reply with OK if this router works."

Anthropic-compatible routers

export ANTHROPIC_BASE_URL="https://agentrouter.org/"
export ANTHROPIC_AUTH_TOKEN="sk-your-key"
export ANTHROPIC_API_KEY="sk-your-key"

Unified routers and gateways

These services are optional. Review privacy, reliability, current pricing, and model availability before sending production or sensitive traffic.

9Router

9Router exposes connected providers through an OpenAI-compatible endpoint. Install it only when you need a separate routing layer; Zeline can already connect directly to many providers.

npm install -g 9router
9router

Deployment options

Run, verify, and connect

# Start the router, then confirm it answers before touching Zeline
curl -s http://127.0.0.1:20128/v1/models | head

# Point Zeline at the local router
zeline config set OPENAI_BASE_URL http://127.0.0.1:20128/v1
zeline config set OPENAI_API_KEY your-router-key
zeline model

FreeLLMAPI

FreeLLMAPI is a third-party open-source gateway. Review its source, supported connectors, and security model before deployment; free provider behavior can change without notice.

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
docker compose up -d

What it does

FreeLLMAPI aggregates several free provider connectors behind one OpenAI-compatible endpoint. It is community software: read the repository, check the connector list, and pin a known commit before you rely on it.

Container deployment

# Review docker-compose.yml first, then start it
docker compose up -d
docker compose logs -f --tail 50

# Confirm the endpoint answers
curl -s http://127.0.0.1:3000/v1/models | head

Unimodel

Unimodel provides one hosted API surface for multiple AI models. Create an account, copy the current base URL and API key from its dashboard, then add it as a custom OpenAI-compatible provider in Zeline. Model names and free-tier limits can change, so use the dashboard as the source of truth.

zeline model
# Choose a custom OpenAI-compatible endpoint
# Enter the Unimodel base URL, API key, and exact model ID shown in your dashboard

Step-by-step setup

Configure Unimodel as a custom provider

# Base URL and key come from the Unimodel dashboard
zeline config set OPENAI_BASE_URL https://www.unimodel.ai/v1
zeline config set OPENAI_API_KEY sk-uni-your-key

# Or export them for the current shell only
export OPENAI_BASE_URL="https://www.unimodel.ai/v1"
export OPENAI_API_KEY="sk-uni-your-key"

# Verify
curl -s $OPENAI_BASE_URL/models -H "Authorization: Bearer $OPENAI_API_KEY" | head
zeline model
zeline chat -q "Reply with OK."

Model families commonly listed

Connect Telegram

Connect messaging only after local chat works. Always restrict access to authorized user IDs so a public bot cannot consume your provider quota.

zeline gateway setup
zeline gateway install
zeline gateway start
zeline gateway status

Other platforms

Zeline supports 20+ messaging and gateway surfaces. Availability and setup requirements vary by adapter.

Gateway operations and security

Messaging adapters have full agent capabilities, so access control matters. Use allowlists or pairing, keep secrets redacted, and retain approval checks for destructive commands.

zeline gateway status
zeline gateway restart
zeline pairing list
zeline status --all

Extend the agent

Once the core path is stable, add voice, automation, skills, MCP integrations, profiles, webhooks, and durable project context.

Memory and profiles

Memory stores durable user and environment context; profiles isolate complete Zeline instances. Do not mix memory, project rules, and SOUL.md—they solve different problems.

zeline memory status
zeline profile list
zeline profile create research
zeline auth list

MCP, plugins, webhooks, and hooks

Extend Zeline without editing core. Connect MCP servers, install plugins, subscribe webhook routes, or attach lifecycle hooks.

zeline mcp list
zeline mcp add NAME --url https://example.com/mcp
zeline plugins list
zeline webhook list

Voice mode

Incoming voice can be transcribed with local faster-whisper or hosted providers. TTS can use Edge TTS or configured commercial providers.

/voice on     # voice-to-voice
/voice tts    # always answer with audio
/voice off    # disable voice output

Cron and scheduled work

Use durable jobs for recurring briefings, reminders, monitoring, and script-driven collection. Test output manually before enabling a production schedule.

zeline cron list
zeline cron create "every 2h"
zeline cron status

Skills and reusable workflows

Skills package procedures, references, templates, scripts, and assets. Inspect third-party skills before installing them and keep only what your workflow needs.

zeline skills browse
zeline skills search telegram
zeline skills inspect <skill-id>
zeline skills install <skill-id>

Where to find skills

Skills are portable procedures. Beyond the official catalog, two community hubs index third-party skills. Read a skill before installing it: a skill can run commands on your machine.

SOUL.md and personality

SOUL.md defines durable identity, tone, and boundaries. Keep it declarative, concise, and free of temporary tasks or secrets.

# My Agent

I communicate clearly, protect private data, verify facts with tools, and ask before destructive actions.

Four personality tiers

Pick the tier that matches how much autonomy you actually want. You can start conservative and widen later — the file is plain Markdown and takes effect on the next session.

Tier 1 — Basic

# SOUL.md

## Identity
I am a careful, helpful assistant.

## Communication
- Answer the question directly, then add context if useful.
- Match the language the user writes in.
- When a request is ambiguous, ask one clear question.

## Boundaries
- Confirm before deleting, overwriting, or sending anything externally.
- Never print secrets, tokens, or private paths.

Tier 2 — Pro

# SOUL.md

## Identity
I am an execution-focused engineering assistant.

## Traits
Direct. Concrete. Verifiable.

## Communication
- Lead with the answer or the command; keep explanation short.
- Reference exact file paths and commands.
- No filler, no motivational language, no unnecessary disclaimers.

## Working style
- Verify results with a real check instead of assuming success.
- Ask only when a decision has a real trade-off.

## Boundaries
- Confirm before destructive or irreversible operations.
- Keep credentials out of output and out of version control.

Tier 3 — Expert

# SOUL.md

## Identity
I am a senior autonomous operator for engineering and product work.

## Traits
Decisive. Rigorous. Self-correcting.

## Communication
- Deliver the outcome first, then the minimum supporting detail.
- Surface risks explicitly instead of hedging.

## Working style
- Plan multi-step work, execute without asking for each step.
- Prove every external side effect with a verifiable handle.
- Turn a repeated successful workflow into a skill.

## Boundaries
- Still confirm destructive, irreversible, or publishing actions.
- Never bypass authentication, quotas, or platform rules.
- Never store or echo secrets.

Apply it

# Save your chosen tier here
$EDITOR ~/.zeline/SOUL.md

# Personality loads at session start
zeline

CLI, TUI, Desktop, Dashboard, and IDE

The same Zeline core is available through multiple interfaces. Choose the surface that fits the job rather than rebuilding the agent.

zeline
zeline desktop
zeline dashboard
zeline acp
zeline proxy

Delegation, goals, Kanban, and worktrees

Scale beyond one conversation with isolated subagents, durable goals, multi-profile task boards, and Git worktrees for parallel coding.

Official resources and version-sensitive data

Zeline evolves quickly. This guide favors official documentation for commands and first-class integrations. Community routers—9Router, FreeLLMAPI, and Unimodel—are clearly labeled optional and are not official Zeline integrations.

Command cheat sheet

zeline setup
zeline model
zeline doctor
zeline tools list
zeline skills list
zeline gateway status
zeline sessions list
zeline cron list
zeline status --all

Troubleshooting

Start with the health check, then inspect the exact component that failed. Restart the gateway after gateway or provider configuration changes.

zeline doctor
zeline status --all
zeline gateway status
grep -i "failed to send\|error" ~/.zeline/logs/gateway.log | tail -20