Manage development services
Start a project preview through the conversation and inspect its process, port readiness, logs, and lifecycle.
Your workspaceRun a local preview as a managed service#
Onevium can manage processes intended to keep running, such as website previews and APIs. A service record includes its name, command, directory, process, and ports, with stop and restart actions for that service.
Explicitly ask to start it as a managed development service. An ordinary terminal command, nohup, or a one-off background build is not the same thing.
Prepare a minimal demonstration project#
This example requires Node.js already installed locally. It does not need npm install or a third-party project download. First run:
node --version
If the command is unavailable, prepare a Node.js environment before continuing. Onevium's internal runtime does not guarantee that node exists in your terminal.
Follow the project guide to create onevium-service-demo. In this empty project, ask the agent to create server.mjs with this complete content:
import { createServer } from "node:http";
const port = 4173;
const html = `<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Onevium service demo</title>
<h1>Onevium service demo</h1>
<p>The local preview is ready.</p>
</html>`;
createServer((request, response) => {
console.log(`${new Date().toISOString()} ${request.method} ${request.url}`);
response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
response.end(html);
}).listen(port, "127.0.0.1", () => {
console.log(`READY http://127.0.0.1:${port}`);
});
Create only the file initially; do not start it in the background of an ordinary terminal. The example listens on the local loopback address. A local preview is not a public deployment.
Start the demonstration service#
Send this in the same project's conversation:
List managed services first and check for this project's existing demo service.
If none exists, confirm server.mjs is saved here and port 4173 is free.
Start node server.mjs as a managed development service:
name onevium-service-demo, cwd set to this project's absolute path,
readiness log marker READY, automatic restart policy no.
Do not stop other processes. If the port is occupied, report it and wait.
Return the service ID, process, port, and readiness state, then open the local preview.
The request should use Onevium's run_service capability rather than merely print a command in the answer. If an approval appears, verify node server.mjs and the demonstration project's directory.
The expected address is http://127.0.0.1:4173. To reopen it later, ask the conversation to open that address in the built-in preview.
Check the process, port, and page#
Open the current conversation's Activity Panel and find onevium-service-demo under Processes. Its row shows the name, running state, port, and recent output. Hover over the name to inspect the command.
| Check | Expected result |
|---|---|
| Process | The service has a real process and does not exit immediately |
| Readiness | Port 4173 is detected, or the log contains READY |
| Page | The built-in preview shows Onevium service demo and The local preview is ready. |
| Request log | Opening or refreshing the page adds request lines such as GET / |
A running process and a ready port do not establish that the page is correct. Inspect the actual page too. For recent full logs, ask “Read the last 50 lines of this service's log,” specifying the returned service ID. The row's last output line is not the complete log.
Stop, restart, and return later#
- Stop: click the square stop button on the intended service row. Refresh the preview afterward; it should no longer fetch a new page from that port. A previously rendered page may remain visible.
- Restart: click the circular arrow or ask to restart the specific service ID. Restart preserves the original command and service record; check the new process and readiness afterward.
- Return later: ending a conversation does not automatically end a persistent service. List existing services before starting another one.
- Clear completed: the panel's cleanup removes finished records; it does not stop running services.
Stop onevium-service-demo when finished. If you change its port, update the demonstration file and verify it again rather than killing an unrelated process on that port.
Troubleshoot startup#
| Symptom | Next step |
|---|---|
node is not found | Repeat the prerequisite check and ensure the terminal/service environment can locate Node.js |
| The port is occupied | Identify its owner. Reuse this project's existing service or choose a free port; do not kill an unknown process |
| The process exits immediately | Read that service's log and check the filename, syntax, and working directory |
| It runs but is not ready | Check the actual listening port and READY output; running and ready are separate states |
| The page is wrong | Check address, port, and service directory for another project's preview |
| A record remains after reopening Onevium | Check process, readiness, and page again. A restored record is not a completed verification |
Next steps#
Use browser automation to check further page behavior. See files, terminal, and Review for edits and diffs, and permissions for action boundaries.