Server
tnsai-server runs TnsAI agents behind a WebSocket API. A client opens a session, chats with that session's agents, and approves their risky tool calls. By default the server listens on 127.0.0.1:7777 and stops after 30 minutes with no connections.
Quick start
Build the executable JAR from the framework source tree. The docker profile is the only build that produces it:
mvn -B -pl tnsai-server -am -Pdocker package -DskipTestsThen run it:
java -jar tnsai-server/target/tnsai-server-*-shaded.jar --port 7777tnsai-server/Dockerfile builds the same JAR into an image. Run docker build from the root of the source tree, because the build copies the other modules. The image binds to 0.0.0.0, so it refuses to start unless you set TNSAI_TOKEN.
To start the server from your own code, see Running the server.
Options
A flag wins over its environment variable.
| Flag | Environment variable | Default |
|---|---|---|
--port <n> | TNSAI_PORT | 7777 |
--idle-timeout <minutes> | TNSAI_IDLE_TIMEOUT | 30 |
--host <address> | TNSAI_HOST | 127.0.0.1 |
--allow-public | TNSAI_ALLOW_PUBLIC=true | off |
TNSAI_TOKEN | auth disabled | |
TNSAI_ALLOWED_ORIGINS | loopback origins only | |
TNSAI_WORKSPACE_ROOT, TNSAI_WORKSPACE_MAX_FILES | working directory, 50,000 files |
A host other than loopback needs both --allow-public and TNSAI_TOKEN; otherwise the server refuses to start. Server hardening covers each setting.
Choosing the model
The server picks one LLMClient at startup, in this order:
- The first
LLMClientregistered throughServiceLoaderon the classpath. - When
TNSAI_PROVIDERandTNSAI_API_KEYare both set:ollamais the only accepted provider, withTNSAI_MODELorqwen3:8bas the model, and the key is not used. Any other provider stops startup withIllegalStateException. - Otherwise, an
OllamaClientforTNSAI_MODEL, orglm-5:cloudwhen it is unset.
To use another provider, start the server from code and pass your own llmClientSupplier.
Endpoints
| Path | Purpose |
|---|---|
/chat | WebSocket protocol for sessions, chat and approvals |
/health, /health/live, /healthz | Health summary and liveness |
/health/ready, /readyz | Readiness |
/api/info | Server information |
/api/index, /api/index/status | Index a directory into a session, check progress, clear the index |
/api/search | Search a session's index |
/api/audit | Read a session's audit trail |
Read next
| To | Read |
|---|---|
| Start the server from code, and see the tools each agent gets | Running the server |
| Write a client | WebSocket protocol |
| Decide which tool calls need approval | Tool approval |
| Log or run commands around tool calls | Tool call hooks |
| Expose the server beyond localhost | Server hardening |