Install and requirements

SmartDecision runs on a Linux server with Docker. One script installs it with your license key and starts it on port 8080.

Requirements

  • A Linux server, amd64 or arm64.
  • Root, or a user with sudo.
  • Docker with the compose plugin. If Docker is missing, the installer installs it. If the compose plugin is missing, install the docker-compose-plugin package and run the installer again.
  • Internet access to get.smartdecision.io while you install or upgrade.
  • Port 8080 free on the server.
  • Your license key, from your welcome email.

The app and the built-in AI run as separate containers. The app is small. The built-in AI needs more memory, but only while someone is drafting a decision: the model loads when you open New decision and unloads after 10 minutes without use. Resolving decisions never uses it.

App only With built-in AI (minimum) With built-in AI (recommended)
CPU 1 vCPU 2 vCPUs 4 vCPUs
Memory 512 MB 8 GB 16 GB
Storage 1 GB 8 GB 18 GB
GPU Not used Not required Not required

"App only" also applies when you point SmartDecision at your own AI server, or run it without AI.

Without a GPU, drafting takes a while. On 4 vCPUs the model needs about a minute to get ready. It starts preparing when you open New decision, while you write the policy. Each draft then takes about 30 seconds, and up to a minute for longer policies. With fewer vCPUs it is slower.

Install

On the server, download the installer and run it:

Shell
curl -fsSL https://get.smartdecision.io/install.sh -o install.sh
sh install.sh

The installer:

  1. Asks for your license key. Paste it from your welcome email.
  2. Asks how SmartDecision should draft decisions: the built-in AI, your own AI server, or no AI. See AI: built-in or your own.
  3. Checks Docker, and installs it if it is missing.
  4. Downloads the newest SmartDecision version your key covers, checks its checksum and loads it into Docker.
  5. With the built-in AI, downloads the model (about 2.5 GB). If the download stops, run the installer again and it resumes.
  6. Writes its configuration to ~/.smartdecision and starts SmartDecision.

When it finishes, open http://<your-server>:8080 in a browser and go on to First sign-in.

Unattended installs

Pass the answers as options and the installer asks nothing:

Shell
sh install.sh --license=SD1.your-key --llm=builtin
Option What it does
--key=KEY Downloads with this license key. It is saved for later runs. An admin still adds the key in the app.
--license=KEY Same as --key, and also installs the key in the app as SMARTDECISION_LICENSE. The key can then only be changed on the server. See Entering a key.
--llm=builtin|external|none The AI choice: built-in AI, your own AI server, or no AI.
--llm-url=URL With --llm=external: the endpoint's base URL, for example http://gpu-box:11434/v1.
--llm-model=NAME With --llm=external: the model name to request.
--llm-api-key=KEY With --llm=external: an API key for the endpoint, if it needs one.
--version=VERSION Installs that version, like 1.4.0, instead of the newest one your key covers.

Servers without internet access

On a machine that has internet access, open get.smartdecision.io and paste your license key to download the image and install.sh. Email support@smartdecision.io if you need help with an offline install.

What gets installed

SmartDecision runs as a Docker Compose project named smartdecision. Everything it keeps lives in ~/.smartdecision in the home directory of the user who ran the installer:

Path What it is
local.db The database: users, projects, decisions, tests, secret keys and the activity log. Back this up.
all.log The app's log file. The app writes its log here, not to docker logs.
.env Settings: the AI choice and endpoint, and the license key. Readable by its owner only.
compose.yaml The Compose file for the two containers.
llm-config.yaml Configuration for the built-in AI.
models/ The built-in AI's model file, when you use it.
images/ Temporary space for downloads. It is emptied after each install.

There are two services:

  • app (container smartdecision): the web app and the Resolve API, published on port 8080.
  • llm (container smartdecision-llm): the built-in AI. It is in the ai Compose profile, so it runs only when you chose the built-in AI. It is not published on the host: only the app can reach it.

To manage the containers, run Compose from that directory:

Shell
cd ~/.smartdecision
sudo docker compose ps          # what is running
sudo docker compose up -d       # start, or apply changes to .env
sudo docker compose restart app # restart the app
sudo docker compose logs llm    # the built-in AI's output

Running the installer again rewrites .env, compose.yaml and llm-config.yaml. It keeps your license key, but asks the AI question again unless you pass --llm. Don't customise compose.yaml or llm-config.yaml by hand.

The installer also adds a smartdecision command to your shell (open a new shell to use it). If you lose the admin password, reset it with:

Shell
smartdecision admin cpass

SmartDecision serves plain HTTP on port 8080. To serve it over HTTPS, put your own reverse proxy in front of it.

AI: built-in or your own

The AI only drafts decisions from policy text. Editing, testing and resolving work the same without it. You choose one of three options when you install, and you can switch by running the installer again.

Built-in AI

The installer downloads a pinned model, Qwen3-4B-Instruct-2507 (Q4_K_M, about 2.5 GB, Apache-2.0 license), to ~/.smartdecision/models, and turns on the ai Compose profile. The llm container starts the model on the first request and stops it after 10 minutes idle, so the memory is used only while someone is drafting. The model runs on your server and nothing is sent elsewhere.

Your own AI server

Point SmartDecision at your own AI server, for example Ollama, vLLM or llama.cpp's llama-server. It must serve chat completions at /v1, the API these servers share, with structured outputs (response_format of type json_schema), and accept temperature and seed.

When you draft a decision, SmartDecision sends the policy text to this server. Run it inside your network to keep your data there. SmartDecision uses these settings:

  • LLM_URL: the base URL, including /v1. The app calls LLM_URL/chat/completions to draft, and LLM_URL/models to check that the AI is available.
  • LLM_MODEL: the model name sent with each request.
  • LLM_API_KEY: sent as Authorization: Bearer <key> when set.

The app runs in a container, so localhost in LLM_URL means the container itself. To reach a server on the same host, use host.docker.internal instead, for example http://host.docker.internal:11434/v1.

SmartDecision's drafting is tuned and tested against the built-in model. Other models can draft differently, so check their tables with tests.

No AI

The Describe a policy option is turned off. You start decisions from a template or from a blank table.

First sign-in

  1. Open http://<your-server>:8080 and sign up. The first account becomes the admin.
  2. Add your license key when asked, or later in Settings → License. If you installed with --license, the key is already in place.
  3. Invite your team from Settings → Invite teammate. Each invitation is a link that works once and expires after 7 days. Everyone after the first account needs one to sign up.

Admins manage members, invitations and the license. Sign-ins last 72 hours. Pending invitations count toward your license's user limit.

Upgrading

Every release is included while your license is active. The changelog lists what changed in each one, and has an RSS feed.

Back up the database first:

Shell
cd ~/.smartdecision
sudo docker compose stop app
cp local.db local.db.backup-$(date +%F)
sudo docker compose start app

Then download the current installer and run it again:

Shell
curl -fsSL https://get.smartdecision.io/install.sh -o install.sh
sh install.sh --llm=builtin

The installer reuses the license key from your last run and installs the newest version your key covers. Pass the same --llm options you installed with, or answer the question again. On start, the new version updates the database by itself. Your data stays in local.db. To install a specific version, add --version=1.4.0.

Environment variables

The installer writes these to ~/.smartdecision/.env, and Compose passes them to the app. After you edit .env, run sudo docker compose up -d in that directory.

Variable What it does
SMARTDECISION_LICENSE The license key. When set, it overrides the key stored in the app, and admins can't change it in Settings.
LLM_URL Base URL of your own AI server. Empty means no AI.
LLM_MODEL Model name sent with each request. The built-in AI uses smartdecision.
LLM_API_KEY Bearer token for the endpoint. Leave empty if it needs none.
LLM_WARMUP true loads the model when someone opens New decision, so the first draft is faster. The installer sets false for your own AI server, so it only loads a model when someone drafts.
COMPOSE_PROFILES ai runs the built-in AI container. Empty does not.

The app also reads two variables that the generated compose.yaml does not pass. They apply only when you run the SmartDecision image with your own Compose file or docker run:

Variable What it does
PORT The port the app listens on inside the container. Default 8080.
JWT_SECRET The key that signs sign-in sessions, at least 32 bytes. Without it, the app generates one on first start and keeps it in the database. Changing it signs everyone out.