Skip to main content

Getting Started

This page takes you from nothing to a working udctl: a running server, a signed-in account, your first card, the ud CLI, and a first job done by your own AI agent. Each step names what you should see when it worked.

1. Pick where udctl runs​

udctl always talks to a server. Pick one of three:

OptionBest forWhat you get
A. Desktop appOne person on a Mac, Windows or Linux machineThe app carries its own backend and signs you in on first launch. Agents run on this machine.
B. DockerYour own server, NAS or VPS, or a machine without a desktopOne container with the web app and backend, opened in a browser.
C. Try in the browserA quick look before installing anythingapp.udctl.com, backed by a test server we run. Do not keep real work there.

Option A: desktop app​

  1. Download the installer for your platform from the Download page.
  2. Open it. The app starts its own backend on http://localhost:24816 and signs you in; there is no account to create.
  3. Your sign-in password is generated per install. You only need it to sign in from somewhere else (a browser, the CLI on another machine); it is shown under Profile → Password.

Continue with step 2.

Option B: Docker​

Needs Docker on the machine. Generate a secret once and keep it for the life of the instance (it also encrypts stored settings, see Set JWT_SECRET before the first start):

openssl rand -base64 48

Start the container, pasting that value as JWT_SECRET:

docker run -d --name undercontrol \
  -p 3000:8080 \
  -e HOST_DOMAIN=http://localhost:3000 \
  -e JWT_SECRET=<paste-the-value-here> \
  -v undercontrol-data:/app/data \
  lintao0o0/undercontrol:latest

Check that it is ready:

docker logs undercontrol

The log ends with a ready banner that says where to go and how to sign in:

  UnDercontrol 0.163.0-020cec4 is ready

  --> Open http://localhost:3000 to get started

      Login as:  personal@undercontrol.local
                 default password: personal123 (set PERSONAL_TIER_PASSWORD to change it)

Open http://localhost:3000, click Log in, and sign in with the email and password from the banner. If the container exits instead, the same log shows a STARTUP FAILED block naming what to fix. Port 3000 taken? Change both -p 3000:8080 and HOST_DOMAIN to another port.

Other ways to run your own server (npm, Homebrew, Kubernetes, PostgreSQL, S3) are in the Self-Deployment Guide.

Option C: try in the browser​

Open app.udctl.com. The sign-in page offers Visitor (No signup) to look around, and Register here for an account on the test server. Data there is for trying the product only.

2. The first-run wizard​

After the first sign-in a short wizard opens with three steps:

  1. Language: English or Chinese.
  2. Machine: explains that agents run on a machine of your own, links the desktop app, and has a Paste to your agent box with setup instructions for your AI agent. Steps 4 and 5 below do the same by hand.
  3. Alfred: your resident assistant, who hands work to agents. He needs a machine to run on (the desktop app, or the ud daemon), so on a plain server you can skip this step for now.

Every step can be skipped; Finish closes the wizard. You land on the task explorer with a Welcome to UnDercontrol! card already in it.

3. Create your first card​

  1. Open Kanban in the left sidebar.
  2. Click Add task at the bottom of a column.
  3. Type a title, for example My first card, and click Create Task.

The card appears on the board right away. Cards hold markdown, so the same card can be a to-do, a document or a meeting note.

4. Install the ud CLI and sign in​

ud is the command-line client. Your AI agent uses it too, so set it up even if you prefer the web app. It needs Node.js 18 or newer:

npm install -g @oatnil/ud
ud --version

Sign in, using the address of your server from step 1:

ud login --api-url http://localhost:3000 -n personal

It asks for your email and password. Replace the URL with yours:

You picked--api-url
Docker (Option B)http://localhost:3000, or the address you gave in HOST_DOMAIN
Test server (Option C)https://api.oatnil.com (register at app.udctl.com first)
Desktop app (Option A)Usually not needed: the app installs the CLI and signs it in for you (context personal) the first time you open a workspace. By hand, it is http://localhost:24816 with the password from Profile → Password.

Check who you are and list your cards:

ud whoami
ud get task

You should see the cards from step 3. Create one from the terminal:

cat <<'EOF' | ud apply -f -
---
title: Try the ud CLI
---
Created from the terminal.
EOF

ud get task now lists it, and it shows up in the web app too. More commands: CLI Reference.

5. Hand your first job to an agent​

udctl works with the AI coding agent you already use (Claude Code, Codex, Cursor and others): the agent reads and writes your cards through ud. The quickest way is to let the agent set ud up for you — paste this one message into it. It is the same message the first-run wizard's Paste to your agent box copies:

I use udctl, a workspace for my tasks, notes and files. You can read and change it from the terminal with the `ud` command. My udctl server is <YOUR-SERVER-URL> — ask me for the address and use it in every command below.

1. Get `ud`. If the udctl desktop app is on this computer, use the `ud` it ships; otherwise npm install -g @oatnil/ud
2. Help me sign in. Never ask me for my password or key and never type them for me. Explain these two ways, let me pick, and wait while I do it:
   a. In my own terminal: ud login --api-url <YOUR-SERVER-URL> -n udctl-<SERVER-HOST> (it asks for my password)
   b. In udctl, Profile → API Configuration → Create Key, then in my own terminal: ud config set-context udctl-<SERVER-HOST> --api-url <YOUR-SERVER-URL> --api-key <my key>
   Use the context udctl-<SERVER-HOST> (add --context if it is not current). Never write to a context named `personal`. Name the context after my server: `udctl-` plus the host, plus the port when it is not the default, with dots and colons as hyphens (http://localhost:3300 -> udctl-localhost-3300, https://api.oatnil.com -> udctl-api-oatnil-com).
3. Learn it: `ud describe skill ud-cli` is the full guide; `ud get skills` lists more.
4. Run `ud config onboarding --done` once. It tells my udctl window you are connected.
5. Then be my guide: tell me in a few lines what I can ask you to do with udctl, ask what I am working on this week, and turn my answer into my first cards.

More about udctl: the website is https://udctl.com. To run it on my own server, the self-hosting guide is https://udctl.com/docs/self-deployment/ and https://udctl.com/llms.txt indexes the rest of the docs — look things up there yourself before asking me. If we get stuck, the udctl Telegram group is https://t.me/+4hZC0GtTe1syYzhl

Replace <YOUR-SERVER-URL> with your server address from step 1. The agent installs ud, helps you sign in (you type your own password or key — it never asks for them), learns the CLI from its skill, runs ud config onboarding --done, and turns what you tell it into your first cards.

Or wire it up by hand​

Give the agent the ud instructions in the project folder you open it in. For Claude Code:

mkdir -p .claude/skills/ud-cli
{ printf -- '---\nname: ud-cli\ndescription: Manage tasks and record progress via notes using the ud CLI.\n---\n\n'; ud describe skill ud-cli -o content; } > .claude/skills/ud-cli/SKILL.md

Other agents load instructions from other paths (AGENTS.md, .cursor/rules/, and so on); ud config onboarding lists them. Then start the agent in that folder and ask for something real, for example:

Use the ud CLI to look at my tasks, then create a card titled "Plan my week"
with a three-item checklist in its body. Tell me the new card's id.

The agent runs ud get task, creates the card with ud apply, and reports its id. The card is in the web app straight away.

Where to go next​