Self-Host Sentio for AI Agents with Localtonet

What Sentio provides and what this guide exposes

Many AI agent workflows need more than a notification address. An agent may need to receive a customer conversation, inspect a parsed message, take an action, and reply in the same thread. Building that flow from separate components commonly means combining SMTP handling, message parsing, authentication checks, malware and spam analysis, storage, queues, webhooks, and outbound delivery.

Sentio's source repository and deployment documentation describe a self-hosted, multi-tenant mail service designed for this use case. A deployment can create domains and mailboxes for agents, deliver inbound messages to application webhooks, and accept outbound operations through a bearer-authenticated REST API. Domains, mailboxes, API keys, rate limits, suppression lists, and spam profiles belong to tenants, which helps separate customers or agent environments within one deployment.

This tutorial covers remote access to the Sentio REST and OpenAPI interface on port 8080. It does not expose the SMTP ports through the same HTTP tunnel, publish the MinIO administration console, or establish a complete production mail-delivery environment. Those surfaces have different protocols, access requirements, and security boundaries.

REST/OpenAPI access is not the Sentio MCP server

This guide connects an AI application directly to Sentio's bearer-authenticated REST API. An agent can use an HTTP client generated from the OpenAPI document or an integration written for the specific operations it needs.

Sentio also ships a separate sentio-mcp server. For the evidenced Sentio v0.1.6 release, that component is distributed as its own archive and points to a running Sentio deployment using SENTIO_BASE_URL and SENTIO_API_KEY. Running the MCP server is optional and requires its own installation and configuration. Creating a Localtonet tunnel to port 8080 does not automatically install, configure, or expose Sentio MCP.

The services behind the REST API

Sentio is not a single stateless HTTP process when deployed as a complete mail platform. Its documented Compose stack starts Sentio together with PostgreSQL, Redis, NATS with JetStream, MinIO, ClamAV, and rspamd.

Prerequisites and deployment choices

The most reproducible installation path is Sentio's official Docker Compose stack. It includes the supporting services and runs migrations during startup, so it is the path used below.

Prepare a Linux host with Docker Engine 24 or newer, the Docker Compose plugin, approximately 4 GB of available memory, and approximately 8 GB of disk space. The published container image supports Linux AMD64 and ARM64. Install Git and curl as well because the workflow uses them to retrieve the repository and test the API.

The commands in this guide pin release v0.1.6, the release reviewed for this tutorial. Sentio behavior, API paths, Compose configuration, and credential-management requests can change between versions. If you select another release, review that version's repository documentation, release notes, Compose file, local /docs interface, and /openapi.json document before exposing it.

Docker Compose versus a manual installation

A manual deployment gives an operator more control over service placement, but it also transfers responsibility for every dependency, migration, credential, and service-manager configuration. This article does not invent systemd units, storage credentials, or undocumented configuration variables. Use the Compose workflow unless you have reviewed the exact manual instructions for your selected Sentio version.

For a manual deployment, verify the actual PostgreSQL server version before applying migrations:

psql -tAc 'SHOW server_version'

PostgreSQL 18 is a strict floor for the documented release because its schema uses uuidv7(). An older server produces a missing-function migration failure. Upgrading the database is the correct resolution rather than removing the function from Sentio's schema.

Install Sentio with Docker Compose

Run the following workflow on the machine that will host Sentio. If the Localtonet client will also run on this host, it can later target the loopback-bound API directly.

git clone https://github.com/truespar/sentio.git
cd sentio

git checkout v0.1.6

docker compose up -d

docker compose logs -f sentio-migrate

docker compose logs -f sentio

Building Sentio from the checkout

If you intentionally want to compile the workspace instead of pulling the published image, use the documented Compose build overlay together with your local override:

docker compose -f docker-compose.yml -f docker-compose.build.yml -f docker-compose.override.yml up -d --build

This performs a release build of the workspace and can take substantially longer than pulling the image. It is useful when auditing or modifying Sentio, but it is not required for ordinary self-hosting.

Restrict direct host exposure before starting the tunnel

The default Sentio Compose configuration lists ports for SMTP, the REST API, and the optional MinIO console. Docker port publication and Localtonet tunneling are independent paths. If Docker publishes 8080 on a LAN, cloud, or public interface, users may be able to reach that listener directly without using the Localtonet URL.

For the REST-only workflow in this article, create docker-compose.override.yml in the repository directory with this content:

services:
  sentio:
    ports: !override
      - "127.0.0.1:8080:8080"

Sentio documents the use of Compose's !override tag to replace its published-port list rather than append to it. In this version, the override leaves the REST API available at 127.0.0.1:8080 while removing host publication for ports 25, 465, 587, and 9001. Containers on the Compose network can still use their internal service connections as configured by the project.

Review the merged configuration before startup:

docker compose config

After startup, inspect the published mappings:

docker compose ps

The displayed REST mapping should identify 127.0.0.1 as the host address. You can also use the operating system's normal socket-inspection tool to confirm that port 8080 is not listening on an external host address.

Treat SMTP listeners separately

Removing SMTP host publications is appropriate for an API evaluation or for a deployment that has not completed its public-mail design. If you later need SMTP delivery, define the required mappings deliberately after reviewing DNS, certificates, port availability, provider policy, and network controls. Do not restore every default mapping merely to make the REST API work.

Port 25 is used for server-to-server SMTP. Port 587 is used for authenticated submission with STARTTLS. Port 465 is for implicit TLS and Sentio skips that listener when the required certificates are not present. These are raw mail protocols and do not belong in the HTTP tunnel configured later.

Treat the MinIO console separately

Port 9001 is an optional object-storage administration console. The REST API does not need that console to be published on the host. Leave it out of the host mapping unless an administrator has a specific need and a separate access-control plan. If local-only console access is required, a separate loopback mapping can be evaluated, but it should not be included in the Sentio HTTP tunnel.

The same controlled-ingress principle applies to other Compose projects. Our Docker Compose exposure guide explains why applications should publish one intentional ingress instead of exposing every container independently.

Verify Sentio locally before exposing it

A tunnel should be the final connectivity layer, not a substitute for local diagnosis. Confirm the Compose services, host binding, readiness endpoint, and version-specific API documentation first.

Check every Compose service

docker compose ps

Review every service rather than only the main Sentio container. The API can start late or report an unhealthy dependency while PostgreSQL, Redis, NATS, storage, or scanning services are initializing. If a service is restarting, inspect its logs before continuing.

Call the readiness endpoint through loopback

curl http://127.0.0.1:8080/health/ready

The documented healthy response is:

{"status":"ok","database":"ok","kv":"ok"}

This proves that the HTTP server answers and that its readiness check sees the database and key-value layer as available. It does not prove that SMTP, public DNS, webhook delivery, storage recovery, or mail reputation are correctly configured.

Inspect the version-specific API description locally

curl http://127.0.0.1:8080/openapi.json

You can also open http://127.0.0.1:8080/docs in a browser running on the host. If you administer the machine remotely, use an access method that preserves the local-only boundary rather than changing the Docker mapping to all interfaces.

The local interactive interface and OpenAPI document are the authoritative runtime references for your installed version's paths, request schemas, response fields, and scopes. Use them when creating replacement keys and selecting a harmless authenticated smoke-test operation. Do not copy a request body from a different release and assume that it remains valid.

Rotate the bootstrap key before any remote exposure

Sentio's documented migration process creates a bootstrap administrator tenant and a bootstrap API key. The initial key has wildcard scope and exists to initialize the deployment. It is not an appropriate runtime credential for an internet-reachable API.

Use the installed version's API documentation

We deliberately do not reproduce the bootstrap secret or guess the replacement-key request body. On the trusted host, consult http://127.0.0.1:8080/docs or http://127.0.0.1:8080/openapi.json. For the reviewed release, Sentio directs operators to create a replacement using the tenant API-key endpoint and then delete the bootstrap key.

Complete the rotation as a controlled local procedure:

1. Retrieve the bootstrap value from the version-specific deployment material on the host.
2. Keep port 8080 restricted to loopback while using it.
3. Open the installed server's local interactive or OpenAPI documentation.
4. Create a replacement administrative key using the request schema documented by that running version.
5. Create a separate, narrowly scoped runtime key for the agent rather than giving it the administrative replacement.
6. Test both replacements locally against operations allowed by their scopes.
7. Update approved secret stores and administrative tooling.
8. Delete the bootstrap key through the documented API.
9. Verify that the deleted bootstrap key receives an authorization failure.

Never place a real key in source control, a frontend bundle, a Compose file committed to the repository, an agent prompt, a screenshot, a support ticket, or the Localtonet tunnel configuration. Localtonet needs its own device authentication token to identify the client, but it does not need the Sentio bearer credential.

Apply least privilege to each agent

An agent that sends messages should not automatically receive tenant-administration privileges. A process that handles mailbox events may not need domain, API-key, suppression, or IP-pool administration. Select scopes using the version-specific API documentation and grant only the operations needed by that workload.

Separate credentials by environment and purpose. Development, staging, production, administrative automation, and customer-specific integrations should not share a wildcard key. This reduces the effect of accidental disclosure and makes revocation more targeted.

Optional Sentio TLS mount

Sentio's documented Compose configuration can mount a certificate and key from a local directory. It expects files named cert.pem and key.pem:

services:
  sentio:
    volumes:
      - ./tls:/etc/sentio/tls:ro

Certificate issuance, renewal, hostname selection, and private-key permissions depend on your deployment. Do not insert placeholder certificates or reuse unrelated private keys. For this guide, Localtonet supplies the public HTTPS address for the HTTP tunnel while Sentio remains on a restricted local target.

Create the Localtonet HTTP tunnel

Continue only after all three pre-exposure gates are complete: the REST listener is restricted, local readiness succeeds, and the bootstrap key has been replaced, deleted, and verified as unusable.

Our client runs on the Sentio host and establishes an outbound connection to a Localtonet relay server. This provides the HTTP access path without inbound router port forwarding, firewall changes, VPN setup, or a public IP address. It does not alter or protect unrelated Docker-published listeners.

Follow the current Localtonet HTTP tunnel documentation while configuring the tunnel. The documentation provides the supported client installation path for your operating system and the current dashboard workflow. Do not substitute an unverified package command from an old article.

Documented Localtonet configuration sequence

Verify the assigned public URL after startup

Public verification is a separate acceptance test after the documented creation and startup workflow. Set the exact assigned HTTPS origin as the base URL and request the readiness path:

export SENTIO_BASE_URL="https://your-assigned-host"
curl "${SENTIO_BASE_URL}/health/ready"

Replace https://your-assigned-host with the address displayed for the running tunnel. Do not append 127.0.0.1:8080 to the public URL. The agent's base URL is the assigned HTTPS origin, while 127.0.0.1:8080 is the Localtonet client's private target.

The tunnel is available only while the selected client remains connected and the tunnel is running. Stop it when remote access is no longer required. Delete it if the configuration should not be retained.

When the Localtonet client runs elsewhere

A loopback target works only when our client and Sentio's host-published REST listener are on the same machine. If the client runs on a different device, 127.0.0.1 refers to that other device and cannot reach Sentio.

Supporting a separate client device requires a private address reachable from that device and an access-control design that restricts who can use the listener. Because network interfaces and firewall systems vary, this guide does not invent a universal rule. Verify the private route from the exact client environment before configuring Localtonet.

The same warning applies when running our client in a container. A container's 127.0.0.1 normally refers to that container, not automatically to the Docker host or the Sentio container. Use a tested container-network target rather than guessing a hostname.

Configure and test an authorized AI agent

The agent needs two separate values:

• Base URL: the assigned Localtonet HTTPS origin, such as https://your-assigned-host.
• Sentio API key: a non-bootstrap key scoped to the operations the agent actually needs.

Store the API key in the agent platform's secret manager, encrypted environment configuration, or another approved credential store. Do not include it in the model's system prompt, conversation context, tool description, source repository, or public URL.

Perform a safe authenticated smoke test

First select a harmless authenticated GET operation that the agent's scoped key is explicitly allowed to perform. Find that path in the installed version's local /docs or /openapi.json. The placeholder below is intentional because the correct endpoint and required scope depend on the Sentio version and the key you created:

export SENTIO_BASE_URL="https://your-assigned-host"
read -s SENTIO_API_KEY
export SENTIO_API_KEY

curl --fail-with-body \
  -H "Authorization: Bearer ${SENTIO_API_KEY}" \
  "${SENTIO_BASE_URL}/VERSION_SPECIFIC_AUTHENTICATED_PATH"

unset SENTIO_API_KEY

Enter the scoped key only when prompted. Do not replace the read -s step with a literal secret in the command because that can leave the credential in shell history or process-related diagnostics. Replace only the path placeholder with the harmless operation verified in your running server's API documentation.

A successful result confirms the public route, bearer-header handling, key validity, and the selected permission. A forbidden response can be the correct result if the key intentionally lacks that scope. Do not widen the key merely to make every endpoint return success.

Verify negative authorization behavior

A useful security test includes an expected failure. Select an operation outside the runtime key's intended scope and confirm that Sentio rejects it. Never perform a destructive request merely to test denial. The local OpenAPI description should identify safe read operations and their authentication requirements for the installed version.

Also confirm that the deleted bootstrap key no longer authorizes requests. Perform that test through the local interface during rotation, before starting the tunnel. Avoid sending a retired wildcard credential over the public path even for testing.

Agent-side configuration pattern

Configure the agent's HTTP tool or generated OpenAPI client so that requests use the Localtonet base URL and add the bearer credential at request time from the secret store. Keep the public base URL and secret as separate settings. The URL may appear in ordinary configuration, but the bearer credential must remain secret.

If the agent uses Sentio MCP instead of calling REST directly, install the separate sentio-mcp component and configure its documented SENTIO_BASE_URL and SENTIO_API_KEY values. The MCP server becomes another credential-bearing component that must be protected. This tutorial does not expose the MCP process itself or assume that MCP is enabled.

Keep inbound application webhooks separate

The tunnel described here lets a remote process call Sentio. If Sentio must call a webhook hosted on another private machine, that webhook needs its own reachable HTTPS route and request-verification policy. Do not reuse a Sentio API key as a webhook-signing secret.

Routine operation and maintenance

Monitor the application and tunnel independently

docker compose ps
docker compose logs sentio-migrate
docker compose logs -f sentio

A Localtonet tunnel can be running while Sentio is unhealthy, and Sentio can be healthy while the tunnel is stopped. Treat these as separate layers:

• Sentio readiness confirms the local HTTP service and selected dependencies.
• The Docker mapping confirms which host interfaces can reach the API directly.
• Localtonet client status confirms that the selected device is connected.
• Tunnel status confirms that the HTTP configuration has been started.
• An authenticated public request confirms end-to-end application access.

Stop Sentio without deleting data

docker compose down

This stops the stack while retaining Compose-managed volumes. After Sentio stops, a running Localtonet tunnel targeting port 8080 has no healthy application to forward to. Stop the tunnel as well when maintenance should not leave a public endpoint returning target errors.

Delete the stack and its volumes

docker compose down -v

Plan upgrades instead of following moving code

Review release notes, image tags, migration behavior, Compose changes, API schemas, and client compatibility before upgrading. Test the target release against a recoverable copy of the deployment and confirm readiness, authenticated API operations, queue processing, storage access, listener bindings, and agent integration.

The exact backup tools depend on whether you use Compose-managed PostgreSQL and MinIO or external services. No universal production backup command is established here. A recovery plan must cover persistent database state and stored message or attachment objects, not only the Git checkout.

Review secrets and access periodically

Inventory administrative keys, runtime keys, Localtonet device tokens, webhook secrets, and any MCP configuration separately. Revoke unused credentials, rotate them according to your operational policy, and confirm that every agent still has only the scopes it needs.

Troubleshooting Sentio and Localtonet

Use a layered test sequence

1. Run docker compose config and inspect the effective port mappings.
2. Run docker compose ps and inspect unhealthy or restarting services.
3. Call http://127.0.0.1:8080/health/ready on the Sentio host.
4. Test a harmless authenticated operation locally with the scoped runtime key.
5. Confirm that the Localtonet client is connected.
6. Confirm that the HTTP tunnel was started after creation.
7. Call the public readiness URL.
8. Perform the same permitted authenticated operation through the public base URL.

This identifies the first broken layer. For example, a successful public readiness response combined with a failed authenticated request usually points to Sentio authorization, scope, or request formatting rather than Localtonet connectivity.

Resolve a port 25 conflict only when SMTP is intentionally enabled

Sentio documents a Compose override that can remap its published ports when another service already uses port 25. That example is useful for local evaluation, but it should not replace the API-only loopback policy without review. Remapping container port 25 to host port 2525 does not make other internet mail servers use port 2525 for ordinary MX delivery.

If you intentionally restore SMTP mappings, inspect the complete merged port list again. Keep the REST API explicitly bound to loopback unless you have implemented an equivalent access-control boundary.

Why production SMTP remains a separate project

The HTTP tunnel solves remote access to Sentio's REST control plane. It does not by itself make the deployment a deliverable, reputable public mail server.

Receiving internet email requires control over a domain and correct MX records leading to a reachable SMTP listener. Sending reliably also involves forward and reverse DNS alignment, PTR records controlled by the address owner, SPF, DKIM, DMARC, TLS, reputation, suppression handling, bounce processing, complaint feedback, and provider-specific policies. Port 25 may be blocked by a hosting provider or ISP, and a nonstandard replacement port is not a transparent substitute for server-to-server SMTP.

Sentio includes substantial mail-protocol and authentication functionality, but those capabilities still require deployment-specific DNS and infrastructure. Localtonet supports raw TCP tunnels, yet that fact alone does not establish that a relay endpoint is suitable for production SMTP, provides the required reverse DNS, or will be accepted by receiving providers. No deliverability claim is made here.

Frequently asked questions