Os Usage

Purpose

Infinite OS is a wildcard container image. It gives you a host-in-a-box experience: applications, the services they need, databases, a web server, and a scheduler, all managed from one dashboard, CLI, and REST API. The container becomes the host you need after you run it.

Use this skill to deploy an instance, deploy WordPress or a custom application, install services, map hostnames, issue TLS certificates, create databases, and schedule jobs.

Procedure

1. Check your position

Before you deploy anything, find out where you are and what is available:

1. Run os version. If it answers, you are inside an Infinite OS container. Skip to step 3.
2. Run command -v docker and command -v podman. If neither answers, stop and ask the user to install Docker or Podman, or to run you inside an Infinite OS container. Do not install a container runtime on your own.
3. List the running containers with docker ps or podman ps. If an Infinite OS container already runs, note its name (every command below will use it as the docker exec <container> prefix) and skip to step 3.
4. Otherwise, deploy an instance in step 2.

2. Deploy Infinite OS

docker run -d --name 'myapp.net' \
  --env 'PRIMARY_VHOST=myapp.net' \
  -p 8080:80 -p 8443:443 -p 1618:1618 \
  docker.io/goinfinite/os:latest

• PRIMARY_VHOST sets the domain the instance serves. The container auto-detects it from the hostname if unset.
• Port 1618 serves the dashboard and the API. It is the only required port.
• Ports 80 and 443 serve the deployed applications directly. Publish them when you do not use a reverse proxy. Map them to 8080 and 8443 on the host when the host ports are taken.
• Run the container as a long-lived instance. The container itself is the unit of state: the whole filesystem holds the OS databases, the deployed applications, and their data. Do not treat the container as disposable.
• The container name usually matches the domain.
• Any OCI runtime works: Docker, Podman, Kubernetes, and others. Container platforms such as Infinite Ez, Kubernetes, and Coolify can run the image too. Infinite Ez, our PaaS, runs one OS container per account, like cPanel runs one account per customer, and can snapshot the entire container to a downloadable .zip to move it to another instance.
• Replace -d with -it to run an attached session.

Open https://localhost:1618/. The first login runs a setup wizard that creates the admin account. The instance uses a self-signed certificate, so the browser warns once.

3. Run OS commands

The CLI is the recommended path for an agent. It needs no authentication. It runs as root, and os refuses to run as any other user.

Outside the container, prefix every command with the container name. Run docker exec <container> os <command> instead of os <command>, for example docker exec myapp.net os services get. Copy files with docker cp. Inside the container, run the commands as written.

• os <command> --help lists the flags and marks the required ones.
• os mktplace list-catalog lists deployable applications with their slug, id, and data fields. The list paginates at 50 items per page; filter with -s <slug> or raise --items-per-page.
• os services get-installables lists installable services: runtimes, databases, and web servers. The list paginates at 10 items per page; raise --items-per-page to see them all.

Use the API only when the container shell is out of reach. Use the dashboard for a human.

4. Deploy a marketplace application

os mktplace install -s wp -n myapp.net \
  -f 'adminUsername:admin' -f 'adminPassword:...' \
  -f 'adminMailAddress:user@example.com'

• -s is the catalog slug, for example wp for WordPress, and -i the catalog id. Use one of them. List both with os mktplace list-catalog.
• -n sets the hostname. Omit it to use the primary virtual host.
• -d sets the URL path. Omit it to serve at the hostname root.
• -f key:value passes one installation data field. Repeat it. The catalog lists each item's dataFields, with name, isRequired, defaultValue, and options.

The install pulls the dependencies, creates the service, starts it, and creates the mapping. Check os mktplace list and os services get. Remove an installation with os mktplace delete -i <installedId>.

5. Deploy a custom application

Clone or copy the project into the container. The container ships git, so clone directly:

docker exec <container> git clone <repoUrl> /app/myapp

Every hostname other than the primary virtual host must exist before a mapping or a service -H references it. Create it with os vhost create -n <hostname> -t top-level.

PHP

Install the php-webserver runtime, map the hostname to it, and pick the PHP version. The mapping creates the PHP virtual host, which serves the vhost root. Keep the project in /app/myapp and replace the vhost directory with a symlink to its public directory:

os vhost create -n blog.myapp.net -t top-level
docker exec <container> rmdir /app/html/blog.myapp.net
docker exec <container> ln -s /app/myapp/public /app/html/blog.myapp.net
os services create-installable -n php-webserver -v 8.3
os vhost mapping create -n blog.myapp.net -p / -t service -v php-webserver
os runtime php update -n blog.myapp.net -v 8.3

A flat PHP app can live directly in /app/html/<hostname>/ instead. For a Composer project, install Composer after php-webserver:

docker exec <container> php -r "copy('https://getcomposer.org/installer', '/tmp/composer-setup.php');"
docker exec <container> php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer
docker exec <container> rm /tmp/composer-setup.php
docker exec <container> bash -c 'cd /app/myapp && composer install'

Laravel

Create the database with os db create and os db create-user, then prepare the app and make its writable directories writable by the web server (nobody:nogroup):

docker exec <container> bash -c 'cd /app/myapp && cp .env.example .env && php artisan key:generate'
docker exec <container> chown -R nobody:nogroup /app/myapp/storage /app/myapp/bootstrap/cache

Set DB_HOST=127.0.0.1, DB_PORT=3306, DB_DATABASE, DB_USERNAME, and DB_PASSWORD in .env to match the database, then run the migrations:

docker exec <container> bash -c 'cd /app/myapp && php artisan migrate --force'

Enable any PHP module the app needs with os runtime php update-modules.

Node.js, Bun, Python, Ruby, and Java

The service runs a startup file on a fixed port. Create the virtual host, then install the runtime, point it at the project entry file, and set the working directory:

os vhost create -n blog.myapp.net -t top-level
os services create-installable -n node -v lts -f /app/myapp/server.js -w /app/myapp -e PORT=3000 -H blog.myapp.net

The app must listen on the runtime port: 3000 for Node, Bun, and Ruby, 8000 for Python, 8080 for Java. lts in -v is an alias for the current LTS release; os services get-installables lists concrete versions too. A service -p is the internal port nginx proxies to, not a host-published port.

Pass the port and other environment variables with -e name=value, for example -e PORT=3000. For a WebSocket app, register the port as ws, for example -p '3000/ws', so nginx forwards the upgrade headers. When the app needs its own server command, override the start command with -c, for example FastAPI:

os services create-installable -n python -v 3.12 -f /app/myapp/main.py \
  -c '/app/myapp/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000' \
  -w /app/myapp -H blog.myapp.net

Install the app dependencies after the runtime, then restart the service (find its name with os services get). Node uses npm install and Ruby bundle install:

docker exec <container> bash -c 'cd /app/myapp && mise x node@lts -- npm install'
os services update -n <serviceName> -s restart

Python uses uv. It is not part of the runtime, so install it with mise, create a project virtual environment, and install the dependencies into it:

docker exec <container> bash -c 'cd /app/myapp && mise install uv && mise x python@3.12 uv -- uv venv && mise x uv -- uv pip install -r requirements.txt'

Start the app from the virtual environment, for example -c '/app/myapp/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000'.

For Rails, run the migrations with the Ruby toolchain and point config/database.yml at 127.0.0.1:5432:

docker exec <container> bash -c 'cd /app/myapp && mise x ruby@3.4 -- bin/rails db:migrate'

Django

Run it with gunicorn on the runtime port. Add gunicorn to requirements.txt, then override the start command and install the dependencies:

os vhost create -n blog.myapp.net -t top-level
docker exec <container> bash -c 'cd /app/myapp && mise install uv && mise x python@3.12 uv -- uv venv && mise x uv -- uv pip install -r requirements.txt'
os services create-installable -n python -v 3.12 \
  -c '/app/myapp/.venv/bin/gunicorn myproject.wsgi:application --bind 0.0.0.0:8000' \
  -w /app/myapp -H blog.myapp.net
docker exec <container> bash -c 'cd /app/myapp && /app/myapp/.venv/bin/python manage.py migrate'

Add the hostname to ALLOWED_HOSTS and point the database settings at 127.0.0.1:5432. Set STATIC_ROOT to staticfiles, collect the static files, and serve them through a static mapping:

docker exec <container> bash -c 'cd /app/myapp && /app/myapp/.venv/bin/python manage.py collectstatic --noinput'
docker exec <container> ln -s /app/myapp/staticfiles /app/html/blog.myapp.net/static
os vhost mapping create -n blog.myapp.net -p /static -t static-files

Gunicorn is the production default for synchronous Django. Async/ASGI Django uses Uvicorn (often as Gunicorn workers) or Daphne. Granian is the newer Rust-based server that supports both interfaces.

Static sites

Create the virtual host and put the files in its public directory. The mapping falls back to index.html for unknown paths, so client-side routing works:

os vhost create -n blog.myapp.net -t top-level
docker exec <container> git clone <repoUrl> /app/html/blog.myapp.net
os vhost mapping create -n blog.myapp.net -p / -t static-files

For a site that needs a build, clone it outside the vhost root, build it, and copy the output in:

docker exec <container> git clone <repoUrl> /app/myapp
docker exec <container> bash -c 'cd /app/myapp && mise x node@lts -- npm install && mise x node@lts -- npm run build'
docker exec <container> bash -c 'cp -r /app/myapp/dist/. /app/html/blog.myapp.net/'

This covers React, Vue, Svelte, Quasar, and every other frontend that builds to static files. The output directory varies: dist/ for Vite-based builds, dist/spa/ for Quasar, build/ for Create React App, out/ for a Next.js static export.

Next.js and Nuxt render on the server by default, so they run as Node services instead. Create the service with the framework start command, install the dependencies, build, and restart:

os services create-installable -n node -v lts -c 'mise x node@lts -- npm start' -w /app/myapp -e PORT=3000 -H blog.myapp.net
docker exec <container> bash -c 'cd /app/myapp && mise x node@lts -- npm install && mise x node@lts -- npm run build'
os services update -n <serviceName> -s restart

For Next.js, npm start runs next start. For Nuxt, start node .output/server/index.mjs after the build, and set the cache URL with -e REDIS_URL=redis://127.0.0.1:6379.

This path uses nginx and ignores .htaccess. If the site needs .htaccess, use the php-webserver runtime instead. It serves static files and honors .htaccess rewrites:

os services create-installable -n php-webserver -v 8.3
os vhost mapping create -n blog.myapp.net -p / -t service -v php-webserver