For Individual Developers

Alloy works just as well for a solo developer as it does for a large team. You do not need an org chart, a sprint ceremony, or a project manager. This guide shows the simplest possible workflow: create a project, track your work, and stay organized — all from the terminal.

1. Why Alloy for Solo Developers

Most project management tools are designed for teams. They force you into roles, permissions, and processes you do not need when you are working alone. Alloy is different:

Zero-config start. SQLite mode, no database server, no Docker. One binary, one command.
API-first. Script your workflow with curl, automate with cron, or integrate with CI — no UI to click through.
TUI for quick work. The built-in terminal UI (alloy-tui) gives you a vim-style interface for browsing tickets and sprints without leaving the terminal.
MCP for natural language. Ask your AI assistant to create tickets, check status, or log time — the MCP server translates intent into API calls.
Scales when you need it. Start solo on SQLite. When your side project becomes a team effort, switch to PostgreSQL and invite collaborators.

2. Getting Started — 5 Minute Setup

Follow the Getting Started guide to install and run Alloy. The short version:

ALLOY_REGISTRATION=open ./target/release/alloy serve

export BASE_URL="http://localhost:3000"
export TOKEN="alloy_live_..."

Create a project for your work:

curl -s -X POST "$BASE_URL/api/v1/projects" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
    \"org_id\": \"$ORG_ID\",
    \"name\": \"side-project\",
    \"key\": \"SIDE\",
    \"description\": \"My weekend project\"
  }" | jq .

{
  "id": "...",
  "org_id": "...",
  "name": "side-project",
  "key": "SIDE",
  "description": "My weekend project",
  "ticket_counter": 0
}

That is it. You have a project. Start adding tickets.

3. The Simplest Workflow

You do not need sprints, workflows, or labels to get started. The simplest workflow is: create a ticket, work on it, mark it done.

Create a ticket:

curl -s -X POST "$BASE_URL/api/v1/projects/$PROJECT_ID/tickets" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
    \"title\": \"Add user authentication\",
    \"status\": \"Open\",
    \"priority\": \"High\",
    \"reporter_id\": \"$USER_ID\"
  }" | jq .

{
  "id": "...",
  "project_id": "...",
  "ticket_number": "...",
  "title": "Add user authentication",
  "status": "Open",
  "priority": "High",
  "reporter_id": "..."
}

Update the status when you start working:

curl -s -X PATCH "$BASE_URL/api/v1/tickets/$TICKET_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"status": "InProgress"}' | jq .

{
  "id": "...",
  "title": "...",
  "status": "InProgress"
}

Mark it done when you are finished:

curl -s -X PATCH "$BASE_URL/api/v1/tickets/$TICKET_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"status": "Done"}' | jq .

{
  "id": "...",
  "title": "...",
  "status": "Done"
}

Three API calls. That is the entire lifecycle. When you need more structure (enforced transitions, review stages), see Workflows & Statuses.

4. Using the TUI

For day-to-day work, the TUI is faster than curl. Launch it:

alloy-tui

The TUI uses vim-style keybindings:

Key	Action
`j` / `k`	Move up and down
`Enter`	Open ticket detail
`n`	New ticket
`e`	Edit ticket
`/`	Search
`q`	Quit

Navigate to your project, see all tickets at a glance, create new ones, and transition statuses — all without leaving the terminal.

See the TUI Guide for the full keybinding reference and configuration options.

5. Using MCP with Your AI Assistant

The Alloy MCP server lets you manage your project through natural language. Connect it to your AI assistant (Claude, etc.) and you can say things like:

“Create a ticket for adding dark mode support”
“What tickets are in progress?”
“Log 2 hours on ticket SIDE-3”
“Give me a summary of the SIDE project”

The MCP server calls the Alloy API on your behalf. It supports all the same operations — creating tickets, transitioning statuses, logging time, running reports.

This is especially powerful for solo developers: instead of context-switching to a browser or remembering API endpoints, just describe what you want in plain English.

See the MCP Guide and MCP Tools Reference for setup and the full list of available tools.

6. Tracking Time

Even solo, tracking time helps you understand where your hours go. Log time against a ticket:

curl -s -X POST "$BASE_URL/api/v1/time-entries" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
    \"user_id\": \"$USER_ID\",
    \"ticket_id\": \"$TICKET_ID\",
    \"project_id\": \"$PROJECT_ID\",
    \"date\": \"2026-03-28\",
    \"duration_minutes\": 90,
    \"description\": \"Implemented auth middleware\",
    \"activity_type\": \"Coding\"
  }" | jq .

{
  "id": "...",
  "user_id": "...",
  "ticket_id": "...",
  "project_id": "...",
  "date": "2026-03-28",
  "duration_minutes": 90,
  "description": "Implemented auth middleware",
  "activity_type": "Coding",
  "status": "Draft",
  "approved_by": null,
  "approved_at": null,
  "created_at": "...",
  "updated_at": "..."
}

Pull a capitalization report to see how you spent your month:

curl -s "$BASE_URL/api/v1/reports/capitalization?period=2026-03" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "period": "2026-03",
  "projects": []
}

When there are approved time entries with labor rates configured, the report includes hours and costs grouped by project.

See Time Tracking & Finance for the full time tracking workflow including approvals and reports.

7. Staying Organized with Labels and Tags

As your project grows, use labels to categorize tickets:

curl -s -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/labels" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "solo-bug", "color": "#e11d48"}' | jq .

{
  "id": "...",
  "org_id": "...",
  "name": "solo-bug",
  "color": "#e11d48",
  "created_at": "...",
  "updated_at": "..."
}

Add labels to tickets for filtering. Use tags for freeform metadata like frontend, backend, blocked, or tech-debt.

See Labels, Tags & Organization for the full labeling and tagging workflow.

8. Growing from Solo to Team

When your project needs collaborators, Alloy grows with you:

Switch to PostgreSQL — For multi-tenant isolation and concurrent access, point ALLOY_DATABASE_URL at a PostgreSQL instance

Invite team members — Send invites with appropriate roles:

curl -s -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/invites" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
    \"email\": \"teammate@example.com\",
    \"role\": \"Member\",
    \"created_by\": \"$USER_ID\"
  }" | jq .

{
  "id": "...",
  "invite_code": "...",
  "invite_link": "...",
  "email": "teammate@example.com",
  "role": "Member",
  "expires_at": "..."
}

Add a workflow — Enforce your process with defined transitions
Start sprints — Organize work into iterations when the team is ready
Set up permissions — Use roles to control who can do what

Everything you built as a solo developer carries forward. No migration, no re-setup. Just add people and process as you need them.

Further reading:

Getting Started — installation and first steps
TUI Guide — terminal UI keybindings and configuration
MCP Guide — natural language project management
Projects & Tickets — creating and managing work
Workflows & Statuses — process enforcement
Time Tracking & Finance — time logging and reports
Labels, Tags & Organization — categorization
API Reference — complete endpoint documentation

Keyboard shortcuts

Alloy Documentation