Profiles

A profile is a named runtime context for Task Manager: its own data directory, auth storage, HTTP port, and (for client profiles) its own remote api_url and api_key. Profiles give you machine-local isolation without mixing data, sessions, or credentials between setups.

Where profiles live

~/.taskmanager/profiles/<profile-name>/
  config.json     # the profile's own settings
  data/           # SQLite database and related files (server profiles only)
  auth/           # auth.json, recovery key, cli-api-keys.json (server profiles only)

A small default-profile pointer lives one level up, alongside the profiles directory:

~/.taskmanager/config.json     # { "default_profile": "main" }

Profile roles

Every profile has a role, set by the wizard mode you choose:

Role	Created by	What this machine does
`server`	`hirotaskmanager --setup-server`	Runs the API server and acts as its own local client. The CLI on the same machine uses `http://127.0.0.1:<port>` automatically.
`client`	`hirotaskmanager --setup-client`	Talks to a remote server only. Contains `api_url` and `api_key`; runs nothing locally.

You never set role by hand — the setup mode picks it. To convert a profile from one role to the other, delete it and re-run the appropriate wizard.

Configuration schema

Field matrix

Field	Server profile	Client profile
`role`	required (`"server"`)	required (`"client"`)
`port`	required	— (must not be set)
`data_dir`	required	—
`open_browser`	optional (default `true`)	—
`bind_address`	optional (default `"127.0.0.1"`)	—
`require_cli_api_key`	optional (default derived from `bind_address`)	—
`api_url`	— (auto-derived as `http://127.0.0.1:<port>` for the local client)	required (absolute URL)
`api_key`	optional (used by the local client when `require_cli_api_key: true`)	required

Auth directory is fixed. The web passphrase hash and CLI API key hashes always live at <profileRoot>/auth/ (i.e. ~/.taskmanager/profiles/<name>/auth/). There is no auth_dir field — the wizard does not prompt for it, and adding one to config.json by hand has no effect.

Validation rules (enforced when the config is loaded)

role must be "server" or "client".
Server profile: port and data_dir are required; api_url must not be present (it is auto-derived from port).
Client profile: api_url (absolute URL) and api_key are required; port, data_dir, open_browser, bind_address, require_cli_api_key must not be present.
Public exposure requires a key. If bind_address is non-loopback (anything other than 127.0.0.1, localhost, ::1), require_cli_api_key: false is rejected.
Bootstrap warning (not an error): if require_cli_api_key === true on a server profile and no api_key is set, the loader warns that the local CLI will fail with auth_cli_key_required until you set one (or pass --api-key per command). External callers may still authenticate via cli-api-keys.json.

Validation failures throw CliError(invalid_config) (exit code 9). The error names the offending field and the profile path.

Example — same-machine server profile (no key)

{
  "role": "server",
  "port": 3001,
  "data_dir": "~/.taskmanager/profiles/main/data",
  "open_browser": true,
  "bind_address": "127.0.0.1"
}

Example — hardened single-host (loopback + forced key)

{
  "role": "server",
  "port": 3001,
  "data_dir": "~/.taskmanager/profiles/main/data",
  "bind_address": "127.0.0.1",
  "require_cli_api_key": true,
  "api_key": "tmk-a3f8c1...local CLI's copy of a key minted via server api-key generate"
}

Example — public bind on the LAN (advanced, hand-edited)

{
  "role": "server",
  "port": 3001,
  "data_dir": "~/.taskmanager/profiles/main/data",
  "bind_address": "0.0.0.0",
  "require_cli_api_key": true,
  "api_key": "tmk-a3f8c1...local CLI's copy of a key minted via server api-key generate"
}

See Advanced: exposing the API on a network interface for when to use this and what to set together.

Example — client profile (talks to a remote server)

{
  "role": "client",
  "api_url": "https://tasks.example.com",
  "api_key": "tmk-a3f8c1...paste full key here"
}

Default-profile pointer

~/.taskmanager/config.json:

{ "default_profile": "main" }

Both --setup-server and --setup-client offer to write this pointer at the end of the wizard. Change it later with:

hirotaskmanager profile use <name>

profile use errors if <name> doesn’t exist on disk.

How the CLI picks a profile

Resolution order, per command:

--profile <name> on the command line (highest priority).
default_profile in ~/.taskmanager/config.json.
If neither is set and exactly one profile exists on disk, use it implicitly.
Otherwise the CLI errors with the list of available profiles and a hint to run hirotaskmanager profile use <name> (or pass --profile).

How a profile is created

Use the wizards in hirotaskmanager. Each one writes the profile’s config.json, optionally mints a CLI API key, and optionally sets the default-profile pointer.

Mode	Use it when	Wizard flag
Server	This machine runs the server (works for both same-machine and VPS installs).	`hirotaskmanager --setup-server`
Client	This machine only talks to a remote server.	`hirotaskmanager --setup-client`

Plain hirotaskmanager with no configured profile asks “server or client?” once, then routes to the right flow. To re-run setup for an existing profile (change port, paths, etc.), use:

hirotaskmanager --setup --profile <name>

Re-running pre-fills your existing answers and refuses role changes — delete the profile and re-setup to convert.

Updating a profile

Interactive: hirotaskmanager --setup --profile <name>.
Manual: edit ~/.taskmanager/profiles/<name>/config.json carefully (keep valid JSON). Back up the file first. Validation errors will surface on the next CLI invocation.

Advanced: exposing the API on a network interface

bind_address is treated as an advanced, config-file-only setting. The setup wizard never asks for it: new profiles always default to 127.0.0.1 (loopback), and re-running the wizard preserves whatever value is already in config.json. When loopback is the right answer:

Same machine. The CLI on this machine talks to http://127.0.0.1:<port> automatically.
Remote access via reverse proxy. Put Caddy, nginx, or similar in front of the loopback API and terminate TLS there. The API stays unreachable from the network directly.

When you want the API socket itself reachable from the network (LAN, Tailscale, etc.), edit config.json by hand and set both fields together:

{
  "bind_address": "0.0.0.0",
  "require_cli_api_key": true
}

The validator enforces this pairing: any non-loopback bind_address (anything other than 127.0.0.1, localhost, ::1) must also have require_cli_api_key: true, set explicitly. Setting bind_address to 0.0.0.0 without require_cli_api_key, or with require_cli_api_key: false, is rejected with invalid_config (exit code 9) on the next CLI invocation. Mint a CLI API key for any caller that will reach the public socket:

hirotaskmanager server api-key generate --profile <name>

Plain HTTP on a non-loopback host sends traffic in cleartext; prefer a reverse proxy with TLS for any access beyond a trusted local network.

Quickstart — same-machine setup.
Advanced setup — VPS / split / hardened / dev workflows.
Concepts — concepts and how the CLI fits the app.
Server operations — server start/stop/status and server api-key ….
Errors & exit codes — invalid_config, auth_cli_key_required, and friends.

Hiro developers only

For Hiro developers working on Task Manager itself, --dev and --profile are independent:

hirotm server start --dev --profile dev
hirotm server start --dev --profile staging
hirotm server start --profile dev

--dev changes runtime behavior, including the default port (3002) and dev CORS.
--profile selects the profile directory for config, auth, and data.
The dev profile is not magic. It is just a profile name.
All profiles, including dev, store data under ~/.taskmanager/profiles/<name>/data/ unless you override the path.

See Advanced setup → For developers for a worked dual-profile example.

Get Started

CLI

Hiro Developers

Where profiles live

Profile roles

Configuration schema

Field matrix

Validation rules (enforced when the config is loaded)

Example — same-machine server profile (no key)

Example — hardened single-host (loopback + forced key)

Example — public bind on the LAN (advanced, hand-edited)

Example — client profile (talks to a remote server)

Default-profile pointer

How the CLI picks a profile

How a profile is created

Updating a profile

Advanced: exposing the API on a network interface

Hiro developers only

​Where profiles live

​Profile roles

​Configuration schema

​Field matrix

​Validation rules (enforced when the config is loaded)

​Example — same-machine server profile (no key)

​Example — hardened single-host (loopback + forced key)

​Example — public bind on the LAN (advanced, hand-edited)

​Example — client profile (talks to a remote server)

​Default-profile pointer

​How the CLI picks a profile

​How a profile is created

​Updating a profile

​Advanced: exposing the API on a network interface

​Related

​Hiro developers only

Where profiles live

Profile roles

Configuration schema

Field matrix

Validation rules (enforced when the config is loaded)

Example — same-machine server profile (no key)

Example — hardened single-host (loopback + forced key)

Example — public bind on the LAN (advanced, hand-edited)

Example — client profile (talks to a remote server)

Default-profile pointer

How the CLI picks a profile

How a profile is created

Updating a profile

Advanced: exposing the API on a network interface

Related

Hiro developers only