> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Startup tasks & services
> Automate environment setup and define repeatable actions for humans and agents.
Tasks and services automate the repetitive work of setting up and operating development environments: seeding databases, starting servers, running tests, authenticating with cloud providers. Define it once and it runs automatically or on-demand.
For agents, tasks and services are essential. When Ona can run `npm test` or `docker compose up` reliably, it can iterate autonomously without human intervention.
## Tasks vs Services
In the session sidebar, long-running processes live under **Ports & Services** and one-off actions live under **Tasks**.
**Services** are long-running processes that stay active throughout your session. They appear in the **Ports & Services** tab alongside the ports they expose.
* Databases (PostgreSQL, MySQL)
* Backend and frontend servers
* Caching systems (Redis)
A service's `start` command must **stay running** (block) for the service to remain active. If the command exits, the service transitions to Stopped (exit code 0) or Failed (non-zero). For example, `npm start` or `docker run postgres` block and keep the service alive, while `docker run -d postgres` returns immediately and the service stops.
**Tasks** are one-off actions that run and complete. They appear in the **Tasks** tab and can run automatically during startup or manually on demand.
* Installing dependencies
* Running tests
* Seeding databases
* Authenticating with cloud providers
## Quick example
```yaml theme={null}
# .ona/config.yaml
services:
database:
name: PostgreSQL
commands:
start: docker compose up postgres
ready: docker compose exec postgres pg_isready
triggeredBy:
- postDevcontainerStart
tasks:
seed:
name: Seed database
command: npm run db:seed
triggeredBy:
- postDevcontainerStart
test:
name: Run tests
command: npm test
triggeredBy:
- manual
```
This configuration:
1. Starts PostgreSQL when the environment starts
2. Waits until the database service is ready
3. Seeds the database with test data
4. Makes "Run tests" available as a manual action
## Apply configuration changes
An environment keeps using the tasks and services configuration that it applied when it was created. Editing, moving, or deleting the configuration file does not change the running environment, including after the environment restarts.
When Ona detects a valid change, the environment start details show that an update is available. Select **Apply** to update that environment. Applying a change uses the latest configuration resolved from the repository; it does not change the Project setting.
If the Project's **Tasks and services configuration path** changed after the environment was created, select **Apply Project configuration** to adopt the new Project setting for that environment. This does not update other existing environments.
If the source file is missing or invalid, Ona keeps the last applied tasks and services running. Restore or fix the file before applying it. A missing or invalid explicitly configured file still prevents a new environment from loading tasks and services.
## Triggers
Control when tasks and services run:
| Trigger | Services | Tasks | When it runs |
| ----------------------- | -------- | ----- | ------------------------------------------------------------------------------------------------------------------ |
| `manual` | ✓ | ✓ | On-demand via the CLI or UI |
| `postDevcontainerStart` | ✓ | ✓ | After the Dev Container starts in a user environment (first start or rebuild). Does **not** fire during prebuilds. |
| `postEnvironmentStart` | ✓ | ✓ | Every time the environment starts or resumes |
| `prebuild` | ✓ | ✓ | During prebuild execution only (no user secrets available). Does **not** fire in user environments. |
See the [.ona/config.yaml schema](/docs/ona/reference/ona-config-schema#triggers) for complete trigger documentation, including [how triggers interact with prebuilds](/docs/ona/reference/ona-config-schema#prebuilds-and-triggers).
## Run automations across repositories
Tasks and services run within individual environments. For cross-repository automation at scale (migrations, security scanning, bulk updates), see [Automations](/docs/ona/automations/overview).
## Next steps
* [.ona/config.yaml schema](/docs/ona/reference/ona-config-schema) - field reference for all fields, commands, triggers, and execution environments
* [Examples](/docs/ona/configuration/tasks-and-services/examples) - common patterns for databases, servers, and CI
* [Dynamic configuration](/docs/ona/configuration/tasks-and-services/generating-tasks-and-services) - create tasks and services programmatically