Skip to main content

Core Concepts

This page defines the core entities and boundaries used across Larktun product, deployment, and operations workflows. These concepts provide a common baseline for network planning, policy design, endpoint onboarding, and incident diagnosis.

Tenant​

A tenant is the top-level management boundary in Larktun. Each tenant owns an isolated network space, member model, ACL policies, and audit data.

  • Individual users can run in a one-user-one-tenant model
  • Enterprises can map tenant boundaries to organizations, departments, or projects
  • Devices, policies, and logs are isolated by default across tenants

Network space and IP pool​

Each tenant has its own virtual address space for endpoint networking and service access.

  • Default address pool is 100.64.0.0/16
  • Custom ranges such as 192.168.6.0/24 are supported
  • Use non-overlapping ranges to avoid conflicts with home, office, or datacenter networks

ACL (Access Control List)​

ACL defines who can access which target resources under what conditions, and is enforced per tenant.

  • Subjects can be defined by users, groups, and device tags
  • Conditions can include time windows, source endpoints, and target ports
  • Approval, temporary grants, and automatic expiration help reduce over-permission

ACLs policy model (multi-tenant)​

In Larktun, ACLs is not just a list of rules, but a complete tenant-scoped policy document. The structure is similar to Headscale ACL concepts, with strict tenant-level isolation for definition and enforcement.

  • Identity layer: users/groups/tagOwners/autogroups
  • Resource layer: hosts/tags/subnets/autogroup:internet
  • Authorization layer: acls (network access) and ssh (session access)
  • Automation layer: autoApprovers (route and exit node auto-approval)
  • Validation layer: tests (policy regression checks)

Policy evaluation is tenant-contained: identity and resource resolution happen only within the current tenant scope.

Devices and device naming​

Devices are the basic nodes connected to the Larktun network, including office endpoints, servers, NAS, industrial equipment, and mobile terminals.

  • Device names are customizable by owner, location, or purpose
  • Tags can be used to group devices for policy management at scale
  • A naming convention is recommended for enterprise operations

Connection paths (direct and relay)​

Larktun prefers direct peer-to-peer paths first and automatically falls back to relay forwarding when direct connectivity is unavailable.

  • Direct path: lower latency and higher transfer efficiency
  • Relay path: stable reachability in NAT-heavy or restricted cross-network environments
  • Path switching is automatic with minimal user disruption

Relay strategy​

Relay servers handle encrypted traffic forwarding when direct paths fail. Choose the mode based on requirements:

  • Shared relay: suitable for individual free users, quick validation, and small-team rollouts
  • Dedicated relay: suitable for enterprises needing stronger stability, capacity, and path control
  • User-managed relay: suitable for organizations with strict region, boundary, or compliance requirements

Subnet Router​

Subnet routers connect private networks that do not run endpoint agents directly into the Larktun tenant network.

  • Publish one or more internal subnets into a tenant network
  • Combine with ACL for fine-grained access control within routed subnets
  • Common for HQ-branch connectivity, datacenter service access, and industrial on-site integration

Exit Node​

An exit node provides unified internet egress for selected devices in a tenant network.

  • Useful when a fixed public egress IP is required
  • Helps enforce consistent outbound policy and audit trails across regions
  • Recommended with ACL, approval flow, and session audit for controlled usage

Magic DNS​

Magic DNS provides stable naming and resolution so endpoints can connect by names instead of raw IPs.

  • Automatically maps device and service names to private network addresses
  • Reduces connection breakage caused by endpoint reinstallation or IP changes
  • Improves daily operations, troubleshooting, and cross-team collaboration

Client agent​

The endpoint agent runs on devices or servers to establish encrypted links and enforce ACL policies.

  • Desktop: Windows, macOS, and Linux
  • Mobile: Android and iOS
  • Designed for low memory footprint, low disruption, and stable long-running sessions

Audit and diagnostics​

Audit and diagnostics support both security governance and troubleshooting workflows.

  • Audit data includes session records, policy decisions, anomaly events, and path quality signals
  • Diagnostics uses logs and path state for faster root-cause analysis
  • Data can be used for permission reviews, risk tracking, and compliance retention

How an access request is applied​

The following flow describes the key stages from request initiation to final access result:

  1. The device joins a tenant network and completes identity authentication
  2. The target is resolved via Magic DNS or direct address
  3. The user or device matches applicable ACL rules and authorization checks
  4. The system selects the path by target type: direct, relay, subnet route, or exit node
  5. The access activity is written to audit logs for diagnostics and compliance lookup