Self-Host Sentio for AI Agents with Localtonet

What Sentio provides for AI agents

Many agent workflows need more than a notification address. An agent may need to receive a customer conversation, inspect the authenticated and parsed message, take an action, and reply in the same thread. Building that flow from separate components usually means combining an SMTP server, message parser, spam and malware checks, storage, queues, an IMAP polling process or webhook layer, and an outbound delivery mechanism.

Sentio packages that path into a self-hosted, multi-tenant mail service. A deployment can create domains and mailboxes for agents, route inbound messages to application webhooks, and accept outbound messages through a bearer-authenticated REST API. Tenancy applies to domains, mailboxes, API keys, rate limits, suppression lists, and spam profiles, which is useful when one application serves multiple customers or separates multiple agent environments.

This guide concentrates on installing and remotely reaching the REST API. It does not attempt to turn an ordinary tunnel into a complete public mail-delivery architecture. Sentio exposes SMTP listeners as well, but production email requires additional DNS, certificate, reputation, and network planning that is separate from making an HTTP API available to an authorized agent.

The services behind the API

Sentio is not a single stateless HTTP binary when operated as a complete mail platform. Its documented Docker Compose stack starts Sentio together with PostgreSQL, Redis, NATS with JetStream, MinIO, ClamAV, and rspamd. These services cover persistent state, key-value operations, queues, object storage, malware scanning, and content analysis.

Prerequisites and deployment choices

The most reproducible installation path is the official Docker Compose stack. It includes the supporting services and applies Sentio's migrations during startup, so this is the path used for the complete procedure below.

Prepare a 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 on AMD64 and ARM64. Ensure that Git and curl are available as well, because we use them to retrieve the repository and verify the local API.

Docker Compose versus a manual installation

A manual deployment gives an operator more control over service placement, but it also transfers responsibility for configuring every dependency, applying migrations, supplying a correct Sentio configuration, and defining a service manager unit. The supplied evidence confirms those requirements but does not provide enough complete configuration content here to reproduce every manual file safely. We therefore do not invent systemd units, environment variables, migration flags, or storage credentials. Use the Docker workflow below unless you have reviewed the exact manual configuration for the Sentio version you intend to deploy.

If you do select a manual deployment, confirm the database version before applying migrations:

psql -tAc 'SHOW server_version'

PostgreSQL 18 is a strict floor. On an older server, the migration fails because uuidv7() does not exist. Upgrading or selecting the correct PostgreSQL server is the proper resolution rather than trying to remove the function from Sentio's schema.

Install Sentio with Docker Compose

The following workflow uses the full official stack. Run it on the machine that will host Sentio and, later, the Localtonet client.

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 complete workspace instead of pulling the published image, use the documented Compose build overlay:

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

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

Understand the published ports

The rest of this guide targets only port 8080. We do not send SMTP ports through the HTTP tunnel because SMTP is a different protocol and public mail delivery has additional requirements.

Verify Sentio locally before exposing it

A remote tunnel should be the final connectivity layer, not a substitute for local diagnosis. Confirm that Sentio and its dependencies work on the host first. This separates application failures from tunnel configuration errors.

Check container state

docker compose ps

Review every service, not only the main Sentio container. The API can start late or report an unhealthy dependency when PostgreSQL, Redis, NATS, storage, or a scanning service is still initializing. If a service is restarting, inspect its logs before proceeding.

Call the readiness endpoint

Sentio documents /health/ready as the readiness check on the local REST listener:

curl localhost:8080/health/ready

A healthy documented response is:

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

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

Inspect the API description

Download or inspect the OpenAPI 3.1 document from the local service:

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

You can also open http://localhost:8080/docs in a browser on a machine that can reach the host. The interactive documentation includes a request client for the running server. Treat that interface as an administrative surface because it helps users discover and call API operations.

Secure Sentio before remote agent access

Sentio's migrations create a bootstrap administrator tenant and a bootstrap API key. That initial key has wildcard scope and is intended to get the installation started. It is not an appropriate credential to leave in place when the API becomes reachable from an untrusted network.

We deliberately do not reproduce the bootstrap secret in this article. Retrieve the initial value from the version-specific Sentio deployment material on the host, use it only over a trusted local connection, create a replacement through the tenant API-key endpoint, update the authorized application, verify the replacement, and then delete the bootstrap key. Never place a real key in a shell history recording, source repository, frontend application, issue report, screenshot, or Localtonet tunnel configuration.

Apply least privilege to agents

An agent that only sends messages should not automatically receive tenant administration privileges. Likewise, a process that reads mailbox events may not need domain, key, suppression, or IP-pool administration. Use Sentio's scoped API-key model to give each integration only the operations it requires.

Separate credentials by environment and workload. Development, staging, production, administrative automation, and individual customer integrations should not all share one wildcard key. This limits the impact of an accidental log entry or compromised agent runtime and makes revocation more targeted.

Review all listeners

Creating an HTTP tunnel for port 8080 does not hide other host ports already published by Docker. Review the host's firewall, cloud security rules, router configuration, and Compose port mappings independently. In particular, do not expose the MinIO console merely because Sentio uses MinIO internally.

Sentio ships without TLS certificates, so it starts its own listeners in plaintext where applicable and skips port 465. For the REST workflow in this article, Localtonet provides a public HTTPS address for the HTTP tunnel, while the client connects from the device to the local target. Do not infer from that arrangement that unrelated SMTP listeners or direct host access have been secured.

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 and are not established by the supplied evidence. Do not insert placeholder certificates or reuse unrelated private keys.

Expose the Sentio REST API with Localtonet

Once localhost:8080/health/ready succeeds and the bootstrap key has been replaced, the Sentio REST listener is ready for the remote-access layer. An HTTP tunnel is the appropriate Localtonet tunnel type because the target is an HTTP API.

Our client runs on the Sentio host, or on another device that can reach the Sentio host, and establishes an outbound connection to a Localtonet relay server. You do not need inbound router port forwarding, firewall changes, VPN setup, or a public IP address for this HTTP access path. The resulting tunnel provides a public HTTPS URL while it is started and its selected client remains connected.

The public readiness check follows this shape, with the assigned URL substituted at review time:

curl https://your-assigned-host/health/ready

Do not copy a private production hostname or bearer token into shared troubleshooting output. For an authenticated API test, use a secret-management method suitable for your agent platform and verify that the selected key can perform only the required operation.

Selecting the local target correctly

Use 127.0.0.1:8080 only when the Localtonet client and the published Sentio API port are on the same machine. If our client runs on a different device, the local target must be an address that device can actually reach. Confirm that route privately before creating the tunnel.

If you run the Localtonet client inside a container, 127.0.0.1 refers to that container rather than automatically referring to the Sentio container or Docker host. Container networking varies by deployment, and the supplied evidence does not establish a universal container hostname. Test connectivity from the exact environment where our client runs instead of guessing.

What remote agents should use

Give the remote agent the public API base URL and a scoped Sentio bearer credential through the agent platform's secret store. The agent can use the OpenAPI description to understand supported operations, but unrestricted exposure of /docs or /openapi.json may disclose unnecessary API structure. Whether to permit those paths depends on your surrounding access controls and threat model.

Keep inbound webhooks conceptually separate from the REST API. The tunnel described here lets a remote process call Sentio. If Sentio must call a webhook running on another private machine, that webhook endpoint needs its own reachable HTTPS route and its own request-verification policy. Do not reuse a Sentio API key as a webhook signing secret.

Routine operation and maintenance

Inspect status and logs

Use Compose to see the current service state and inspect the two most relevant startup logs:

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

A tunnel can remain connected while Sentio is unhealthy, so monitor the application and tunnel as separate layers. Sentio readiness confirms the local application state. Localtonet tunnel status confirms that the selected client is connected and the tunnel is running.

Stop Sentio without deleting its data

docker compose down

This stops the stack while retaining its Docker volumes. After Sentio stops, a Localtonet HTTP tunnel targeting port 8080 has no healthy application to forward to. Stop the tunnel as well if maintenance should not leave a public endpoint returning connection errors.

Delete the stack and its volumes

docker compose down -v

Plan upgrades rather than following moving code

Review release notes, container tags, migration behavior, and compatibility before upgrading. Test the target release against a copy of the deployment and confirm the readiness endpoint, authenticated API operations, queue processing, storage access, and agent integration.

The exact backup tools and upgrade sequence depend on whether you use Compose-managed PostgreSQL and MinIO or external services. The supplied evidence does not define one universal production backup command, so we do not invent one. At minimum, a recovery plan must account for persistent database state and stored message or attachment objects, not just the Git checkout.

Troubleshooting Sentio and Localtonet

Resolve a port 25 conflict during evaluation

If another service already uses port 25, Sentio documents a Compose override that replaces its published port list:

services:
  sentio:
    ports: !override
      - "2525:25"
      - "4465:465"
      - "5587:587"
      - "8080:8080"

Save that content as docker-compose.override.yml. The file is loaded automatically and is ignored by the repository. This can resolve local conflicts for evaluation, but remapping inbound SMTP from public port 25 to 2525 does not make normal internet MX delivery use port 2525. Other mail servers ordinarily connect to the standard SMTP port.

Separate application errors from tunnel errors

Use a layered test sequence:

1. Check the Compose service state.
2. Call localhost:8080/health/ready on the Sentio host.
3. If the Localtonet client is on another device, call the private Sentio address from that device.
4. Confirm that the selected Localtonet client is connected.
5. Confirm that the HTTP tunnel is started.
6. Call the public readiness URL.
7. Finally, test a permitted authenticated operation with a scoped key.

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

Why production SMTP is a separate project

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

Receiving internet email requires control over a domain and correct MX records that lead other mail systems to an 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 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 appropriate for production SMTP, that it provides the required reverse DNS, or that receiving providers will accept mail from it. No such deliverability claim is made here.

Frequently asked questions