Synadia NATS Agents

About the project

A job can take longer than an HTTP request. The gateway puts it in a queue and a worker processes it separately. It needs redelivery and a check against applying a completed result twice.

Synadia console in Vue/Bun, a YouTrack gateway and a separate Codex worker, connected through NATS JetStream. Discovery and diagnostic chat are connected. Running YouTrack tasks still needs access configuration.

• The YouTrack URL and MCP/REST access are not configured. An unreachable placeholder replaces the corporate URL; no requests are sent to the production YouTrack service.
• Codex/OpenAI access has not yet been provided. Task execution and posting comments to YouTrack have not been verified.
• Diagnostic health/hooks/jobs responses come from the gateway, not an LLM.
• Discovery and gateway diagnostics are public. Current Codex Desktop tasks and subagents are not yet connected to the console.

Screenshots, diagrams and source evidence retain their original language; captions and descriptions are translated.

Architecture and diagrams

• The original examples/agent-web-ui is served by Bun; scripts/start-production.js starts the processes.
• The gateway handles webhooks and results; the worker is separate from HTTP and reads a JetStream durable consumer.
• A separate NATS account is used; subjects youtrack.codex.jobs.komaroff and youtrack.codex.results.komaroff belong to stream KOMAROFF_CODEX.
• CODEX_DRY_RUN=false and YOUTRACK_DRY_RUN=false. Missing credentials are not replaced with synthetic responses.
• The console has been open without a password since 7 September 2026. The webhook requires its own token; NATS and the database are not exposed publicly.

Code map: files and dependencies

This map is tied to version d5b786da3c04. The table lists the screen or API, related module and data.

Using the code map

1. Before making a change, find the feature and trace its links to the API, state and storage.
2. Check inputs, errors, repeated events and dependent workflows.
3. After making a change, update the map and affected diagrams alongside the code.
4. Run the related checks and link the new evidence to the source version.

Workflows and API

1. Open the console without signing in; check CONNECTED and the discovered codex NATS agent.
2. Open the agent, send health and receive a real response about JetStream, subjects and consumers.
3. After configuring YouTrack and Codex: webhook → job → separate worker → result → write the result to YouTrack.
4. Check job states, results, redelivery and worker recovery using an agreed test task.

Verification of the published version

CI: Full build of the original application ↗ · d5b786da · this demo's version · 2026-09-07

• The full original image was built in GitHub CI. The API and separate worker are running.
• Synadia UI discovered one real agent; health passed through WebSocket/NATS and returned the state of KOMAROFF_CODEX.
• Both dry-run flags are disabled; NATS and consumer readiness are confirmed.
• Unauthenticated access and webhooks without a token were rejected. Desktop and mobile views were checked.
• No real Codex task or YouTrack write was performed: integration configuration is missing.

These checks apply to the listed version. Business metrics and model quality on an independent dataset were not measured.

Measurements

• Five sequential HTTPS GET requests from the VPS to itself: 8.9–60.7 ms, all HTTP 200. This is not a load test or an assessment of the external network.
• No Telegram collection, LLM processing or Codex task ran during the measurements.

Running and operating

The full image uses the original docker/Dockerfile. App: node scripts/start-production.js; worker: node src/codex-worker.js.

Settings: /srv/portfolio/agents/.env and integrations.env; separate persistent codex-state. Docker resources and logs are limited.

YOUTRACK_BASE_URL and YOUTRACK_MCP_URL or YOUTRACK_TOKEN are required; model access requires the agreed OPENAI_API_KEY/CODEX_API_KEY or another supported method. Do not transfer corporate credentials without the owner's instruction.

Once configured, verify one explicitly selected task: webhook, durable job, session_started, analysis_completed and the result in YouTrack. Until then, this chain remains unverified.

Stack

Materials and source code

Repository history: since 22 May 2026. Published version: 7 September 2026.

The evidence archive retains its original language.