Skip to content

Scordo — User Manual

Purpose

This manual is for end users of the Scordo router and its bundled applications. It covers daily use of the router console, browsing scordosites, sending anonymous email with ScordoMail, resolving mesh addresses with ScordoDNS, and sharing files with Snark.

For installation and deployment, see docs/ADMINISTRATOR_GUIDE.md.

1. What Is Scordo?

Scordo is a privacy-preserving mesh network. All traffic is routed through multiple hops inside the mesh, so neither your peers nor external observers can determine your identity or the content of your communications.

Key concepts:

  • Router — the core process that integrates your device into the Scordo mesh, manages tunnels, and routes encrypted packets.
  • Tunnel — an anonymised path through several intermediate routers used to send and receive traffic.
  • Destination — a stable mesh address for a service or user (similar to an IP address but persistent and identity-preserving).
  • Scordosite — a web service hosted inside the Scordo mesh, accessible via the HTTP proxy.
  • ScordoMail — anonymous email running entirely within the mesh.
  • ScordoDNS — the distributed address book that translates human-readable names to mesh destinations.

2. Getting Started

2.1 Starting the router

If Scordo was installed with the standard installer, it may start automatically at login. You can also start and stop it from the router console or tray icon.

For Docker deployments, the router starts when the container starts. See docs/ADMINISTRATOR_GUIDE.md §3 for container startup commands.

2.2 Opening the router console

Open a browser and go to:

http://127.0.0.1:7657

The console is only accessible from your own device. It is not exposed on the network.

2.3 First start

On first start, Scordo:

  1. Generates a new router identity (takes a few seconds).
  2. Contacts reseed servers to discover initial peers.
  3. Builds tunnel pools for each application.

This process takes 5–15 minutes. The status bar on the console home page shows progress. Network status will move from Testing to OK once tunnels are established.

Do not close the router during this process.

3. Router Console

The router console (http://127.0.0.1:7657) is the main interface for monitoring and configuring your Scordo router.

3.1 Home / Summary page

Shows:

  • Network status — OK, Testing, Firewalled, or Disconnected
  • Active tunnels — how many tunnels are currently built and in use
  • Participating tunnels — how many other routers' tunnels your router is relaying (your contribution to the mesh)
  • Bandwidth — current in/out throughput and cumulative totals
  • Router uptime

A status of Firewalled means external peers cannot reach your transport port. The router still works, but performance is reduced. Contact your network administrator if you need this resolved.

3.2 Navigation

Console section Purpose
Home Status summary, bandwidth overview
Network Database Peer count, floodfill nodes, reseed status
Tunnels Active tunnel pools per application
Peers Peer list with connection quality
Graphs Bandwidth, tunnel build rate, latency charts
Stats Detailed routing and performance statistics
Configuration Bandwidth limits, network settings, tunnels, keyring, update
Help In-router help pages and update function

3.3 Bandwidth settings

To adjust how much bandwidth Scordo uses:

  1. Go to Configuration → Bandwidth.
  2. Set inbound and outbound share limits appropriate for your connection.
  3. Save and apply.

Higher share limits improve tunnel build success for you and other users. Keep settings within what your connection can sustain.

4. Browsing Scordosites

Scordosites are web services hosted inside the Scordo mesh. Their addresses end in .scordo (e.g. example.scordo).

4.1 Configuring your browser

Configure your browser to use the Scordo HTTP proxy:

  • Proxy host: 127.0.0.1
  • Proxy port: 4444

For Firefox:

  1. Open Settings → Network Settings → Manual proxy configuration.
  2. Set HTTP proxy to 127.0.0.1, port 4444.
  3. Check Use this proxy server for all protocols (or set HTTPS proxy the same way).
  4. Optionally, enter localhost, 127.0.0.1 in "No proxy for" to keep local traffic direct.

4.2 Accessing a scordosite

With the proxy configured, enter a .scordo address in your browser's address bar:

http://example.scordo/

The first request to a scordosite may take 10–30 seconds while a tunnel is established to the destination. Subsequent requests are faster.

4.3 The HTTP proxy default page

If you navigate to http://127.0.0.1:4444/ with the proxy configured, you will see the Scordo HTTP proxy page with links to internal services and an address bar for .scordo lookups.

4.4 Addressing

Scordosite addresses are human-readable names registered in the distributed address book (ScordoDNS). If a name is not found, you may need to add a subscription that covers that namespace.

5. ScordoMail — Anonymous Email

ScordoMail provides anonymous email entirely within the Scordo mesh. It does not connect to the public internet.

5.1 Accessing ScordoMail

Open in your browser (Scordo proxy must be running but does not need to be configured in the browser for this):

http://127.0.0.1:7657/webmail

Or navigate from the router console home page to Applications → ScordoMail.

5.2 Setting up your mail account

  1. On first use, create an account with a .scordo email address.
  2. Your address will be of the form username@mail.scordo.
  3. Note: this address is only valid within the Scordo mesh.

5.3 Sending and receiving email

  • Compose messages using the built-in web UI.
  • Attachments are supported.
  • Mail is delivered through the mesh; delivery may take a few minutes depending on tunnel availability.

5.4 External email client (SMTP/POP3)

ScordoMail also exposes local SMTP and POP3 endpoints for use with a standard email client:

Protocol Host Port
SMTP (outbound) 127.0.0.1 7659
POP3 (inbound) 127.0.0.1 7660

Configure these in your email client (e.g. Thunderbird) using plain text authentication (no TLS required as these ports are local-only).

6. ScordoDNS — Address Book and Naming

ScordoDNS is the distributed naming system for the Scordo mesh. It maps human-readable .scordo names to cryptographic mesh destinations.

6.1 Accessing ScordoDNS

From the router console: Applications → Addressbook or navigate to:

http://127.0.0.1:7657/dns

6.2 Adding a hostname

If you know the cryptographic destination of a service and want to give it a local name:

  1. Go to the Addressbook page.
  2. Click Add Host.
  3. Enter the .scordo hostname and the base64 destination string.
  4. Save.

6.3 Subscriptions

Subscriptions are external address book feeds that automatically add hosts to your local book.

To add a subscription:

  1. Navigate to Addressbook → Subscriptions.
  2. Paste the subscription URL (a .scordo address pointing to a hosts.txt file).
  3. Save. The book will update on the next sync cycle.

Default subscription sources are pre-configured in a fresh install.

6.4 Looking up a destination

To resolve a hostname to its raw mesh destination:

  1. Navigate to Addressbook → Look Up.
  2. Enter the hostname.
  3. The cryptographic destination string will be shown if the host is in your local book.

7. Snark — Anonymous File Sharing

Snark is the built-in torrent client for the Scordo mesh. It operates entirely within the mesh; no external trackers are used.

7.1 Accessing Snark

From the router console: Applications → Torrents or navigate to:

http://127.0.0.1:7657/torrents

7.2 Adding a torrent

  1. Open the Snark page.
  2. Click Add Torrent and paste a magnet link or upload a .torrent file.
  3. Select a download directory (default: the Snark volume or ~/scordosnark).
  4. Start the download.

7.3 Seeding

Files you add to Snark are automatically seeded back to the mesh after download. You can also create and publish new torrent files from the Snark interface.

7.4 Download location

Context Default path
Standard install ~/scordosnark/
Docker /scordosnark/ (mount as persistent volume)

8. Tunnel Manager

Tunnels are the building blocks of all Scordo applications. The tunnel manager lets you create custom client (outbound) and server (inbound) tunnels for integrating your own applications with the mesh.

8.1 Accessing the tunnel manager

From the router console: Applications → Hidden Services Manager or navigate to:

http://127.0.0.1:7657/i2ptunnel/

8.2 Tunnel types

Type Use case
HTTP Client Browser proxy for scordosites
HTTP Server Host a scordosite from your machine
SOCKS 4/5 Client Generic SOCKS proxy for any application
Standard Client Connect to any mesh service by destination
Standard Server Expose a local TCP service to the mesh
IRC Client Connect to IRC servers inside the mesh

8.3 Creating a server tunnel (hosting a scordosite)

  1. Go to the Hidden Services Manager.
  2. Click New Tunnel → HTTP Server.
  3. Enter the local host and port of your web service (e.g. 127.0.0.1:8080).
  4. Give the tunnel a name and description.
  5. Save and start the tunnel.
  6. Your service is now reachable at the destination shown in the tunnel detail page.

Register the destination with ScordoDNS if you want a human-readable name.

9. SAM Bridge — Application Integration

The SAM (Simple Anonymous Messaging) bridge provides an API at port 7656 for custom applications to connect to the Scordo mesh without needing to embed a full router.

Custom applications use SAM to create sessions, send and receive datagrams, and establish streaming connections. Refer to the SAM protocol documentation at https://scordo.net/docs for the API specification.

10. Privacy and Security Practices

10.1 What Scordo protects

  • Your IP address is not visible to services you connect to inside the mesh.
  • Traffic between your router and mesh peers is encrypted.
  • Tunnel routing uses multiple intermediate hops so no single node can observe both the sender and receiver.

10.2 What Scordo does not protect against

  • Scordo does not anonymise traffic sent outside the mesh. Configure a trusted outproxy carefully if you use one.
  • Application-level data (e.g. a form you fill in) can still identify you if you enter identifying information.
  • Timing analysis over very long periods may in theory correlate traffic patterns.
  • Do not run Scordo on a shared, untrusted system where other users could access the router console or proxy ports.
  • Do not expose the router console or proxy ports to the network — they should always be loopback-only.
  • Keep the router updated to receive security patches.
  • If you operate a scordosite, do not include content that identifies you unless intentional.

11. Common Problems

Router status stuck on "Testing" or "Firewalled"

  • Allow 15 minutes after first start for tunnels to build.
  • If the router remains in Firewalled state, confirm port forwarding is configured for the transport port (default 12345) and EXT_PORT is set correctly (Docker deployments).
  • Contact your network administrator if you cannot control firewall settings.

Can't reach a scordosite

  1. Confirm the router status is OK in the console.
  2. Confirm the browser proxy is set to 127.0.0.1:4444.
  3. Try refreshing after a 30-second wait — tunnels may be rebuilding.
  4. Check the address in ScordoDNS — the name may not be in your address book.

ScordoMail not loading

  1. Confirm the router is running and status is OK.
  2. Navigate directly to http://127.0.0.1:7657/webmail — no browser proxy needed.
  3. Check the console tunnel list for a ScordoMail tunnel that is active.

Snark download stalled

  1. Check that the torrent has active seeders in the mesh.
  2. Confirm Snark has enough tunnel build budget (visible on the tunnels page).
  3. Try removing and re-adding the torrent.

Router console not loading

  1. Confirm the Scordo process or container is running.
  2. Confirm nothing else is using port 7657: lsof -i :7657 or ss -tlnp | grep 7657.
  3. Restart the router.

12. Updating Scordo

Automatic update (standard install)

  1. The router console shows a notification when an update is available.
  2. Navigate to Help → Update and follow the prompts.
  3. The router restarts automatically after the update.

Manual update

Download and run the latest installer from https://scordo.net/download. Running the installer over an existing installation upgrades the router files without removing your configuration.

Docker update

See docs/ADMINISTRATOR_GUIDE.md §8.1 for the Docker upgrade procedure.

13. Getting Help

  • Help pages (in-console): http://127.0.0.1:7657/help
  • FAQ: https://scordo.net/faq
  • How-to guides: https://scordo.net/how
  • Bug reports: https://github.com/cosimoglobal/Scordo/issues
  • IRC: #scordo on irc.freenode.net
  • Contact / security: https://scordo.net/en/contact

14. Documentation Map

  • README.md — source and build quick-reference
  • Docker.md — Docker and Compose configuration reference
  • docs/ADMINISTRATOR_GUIDE.md — operator deployment and ops guide
  • docs/USER_MANUAL.md — this file
  • docs/HACKING.md — developer build environment and source guide
  • docs/production-program/SCORDO_PRODUCTION_PROGRAM.md — production program phase gates