Projects & Services
Concepts
Project
A project groups related services together (e.g. an entire application stack). Projects are organizational containers — they have no state of their own.
Service
A service is a process managed by Runeya. Each service has:
- A command to execute
- A working directory
- Environment variables
- Streaming logs
- An assigned agent (local by default)
Creating a Project
- Click "+ Project" in the left sidebar
- Give it a name (e.g.
backend,frontend,infra) - The project appears in the list
Creating a Service
Inside a project, click "+ Service" and fill in:
General Tab
| Field | Description | Example |
|---|---|---|
| Name | Display identifier | api, worker |
| Description | Optional notes | Main REST API |
| Command | Executed command | node dist/index.js |
| Directory | Working path | /home/user/my-app |
| Shell | Enable shell mode | false (recommended) |
Shell mode
Enable shell: true only if your command requires redirections (|, >, &&). Prefer decomposing into sub-commands or scripts.
Environment Tab
Attach environments to the service to inject variables. See Environments & Variables.
Logs Tab
Configure log parsers applied to the service's output stream. See Logs & Parsers.
Controlling a Service
| Action | Description |
|---|---|
| ▶ Start | Start the process |
| ⏹ Stop | Graceful stop (SIGTERM → 10s → SIGKILL) |
| 🔄 Restart | Stop + Start |
| 🗑 Delete | Remove configuration (doesn't touch your files) |
Service States
stopped ──► starting ──► running
▲ │
└────────── stopping ◄───┘
│
stopped / error| State | Color | Description |
|---|---|---|
stopped | Grey | Process stopped |
starting | Yellow | Starting up |
running | Green | Process active |
stopping | Orange | Graceful shutdown in progress |
error | Red | Process exited with error code |
Stable Identifiers
A service's ID is stable across Runeya restarts. It serves as processId on the agent side — this 1:1 mapping ensures a service keeps its log history and configuration even after a server restart.