sinkron（sinkron 命令行）

Sinkron

Sinkron enables AI agents to own permanent email addresses and manage inboxes programmatically via a CLI and Python SDK.

Authentication model: SINKRON_TOKEN is self-issued by the Sinkron platform — generated once by the Sinkron backend when sinkron register is run, printed to the CLI, and never again retrievable. There is no third-party OAuth, no external credential service. Existing agents reuse their token from a prior registration.

Official Website: https://www.sinkron.id\ Source: https://github.com/zororaka00/sinkron\ PyPI: https://pypi.org/project/sinkron/

⚠️ Security Pre-flight Checklist

Complete every item before installation. Do not skip.

1. Verify Provenance

• [ ] Open https://www.sinkron.id and confirm it matches the expected project.
• [ ] Visit https://github.com/zororaka00/sinkron and review the source code.
• [ ] Open https://pypi.org/project/sinkron/ and confirm the package owner matches the author (@zororaka00).
• [ ] Pin to a specific version (sinkron==X.Y.Z) — never install without a version pin.
• [ ] If provenance cannot be confirmed, treat this skill as untrusted and do not install.

2. Inspect the Package Before Installing

# Download wheel/tarball without installing, then inspect contents
pip download sinkron==X.Y.Z --no-deps -d /tmp/sinkron-inspect
ls /tmp/sinkron-inspect/
# Unzip the .whl (it's a zip) and review .py source files for
# unexpected network callbacks, obfuscated code, or telemetry

3. Install in an Isolated Environment First

# Preferred: use a container or VM for initial testing
docker run --rm -it python:3.11-slim bash
# Inside container:
pip install sinkron==X.Y.Z
sinkron --help

4. Understand Token Origin Before Use

SINKRON_TOKEN is self-issued — here is exactly where it comes from:

The token never comes from a URL fetch, a third-party service, or this skill itself — only from the Sinkron backend's register response.

After obtaining the token:

• [ ] Store it immediately in a secret manager or restricted .env file.
• [ ] Clear terminal / shell history after the token is displayed.
• [ ] Confirm it is not present in logs, CI output, or version-controlled files.
• [ ] Rotate periodically or after any suspected exposure.

Installation

Step 1 — Check the latest pinned version on PyPI

pip index versions sinkron

Step 2 — Install with a pinned version

# Preferred (pinned version)
pip install sinkron==X.Y.Z

# Alternative via uv (also pin version)
uv tool install sinkron==X.Y.Z

⚠️ Never install without a pinned version. Unpinned installs may pull unreviewed future versions.

Step 3 — Validate installation

sinkron --help

Best Practice Usage Model

1. Installation Policy

Before performing any Sinkron operation:

• Verify sinkron is installed.
• If not, follow the Installation section above (provenance check first).
• Validate with sinkron --help — do not assume success without this step.

2. Token Lifecycle & Management

Where SINKRON_TOKEN comes from

New agent   → sinkron register --username USER --name NAME
                ↳ Sinkron backend responds with: token: <YOUR_TOKEN>
                ↳ Copy this token immediately — it is shown only once
                ↳ Store in secret manager or restricted env var

Existing agent → token was issued during prior registration
                ↳ Set SINKRON_TOKEN directly from secure storage

No third-party service, no OAuth flow, no external dashboard — the token is exclusively generated by the Sinkron backend.

Using the token safely

# After registration: store token (clear shell history after)
export SINKRON_TOKEN="token-from-sinkron-register-output"
sinkron config --token "$SINKRON_TOKEN"

# In CI/CD: inject via secret manager — never hard-code
sinkron config --token "$SINKRON_TOKEN"

• Never log, print, or expose tokens in shell history, logs, or CI artifacts.
• Use sinkron health to check if Sinkron platform is active.
• Rotate tokens periodically and immediately after any suspected exposure.

3. Idempotent Agent Registration

Before registering, check if the username already exists:

sinkron agent USERNAME

Only register if it does not exist:

sinkron register --username USER --name NAME

This prevents duplication and ensures predictable automation flows.

4. Safe Inbox Handling

• Use pagination — avoid fetching large inboxes at once.
• Prefer --search for filtered access.
• Never delete blindly — always review IDs first.

Safe flow:

1. sinkron inbox --search KEYWORD
2. Review IDs
3. sinkron delete-messages --ids 1,2,3

5. Automation Strategy

Always start with a health check:

sinkron health || exit 1

• Log non-sensitive outputs only.
• Implement retry logic on API failures.
• Inject SINKRON_TOKEN via CI secret manager — never hard-code in pipeline files.

6. Python SDK Best Practices

import os
from sinkron import SinkronClient

token = os.getenv("SINKRON_TOKEN")
if not token:
    raise EnvironmentError(
        "SINKRON_TOKEN is not set. "
        "Obtain it from `sinkron register` output and store in a secret manager."
    )

client = SinkronClient(token=token)
messages = client.inbox(page=1)

• Initialize client once per runtime.
• Never hardcode tokens — use environment variables exclusively.
• Implement exponential backoff on failures.

Architecture

Sinkron exposes two operational layers:

1. CLI — operational / DevOps workflows
2. Python SDK — programmatic / application integration

Both communicate with the same Sinkron backend API.

Operational Requirements

• Python 3.8+
• Internet connectivity
• SINKRON_TOKEN environment variable (self-issued via sinkron register)
• Isolated environment (container/VM) recommended for first-time setup

Security Guidelines

• Verify package provenance and inspect source code before installing.
• Pin to a specific package version — never install unpinned.
• Store SINKRON_TOKEN in a secret manager or restricted env var — never in source code.
• Use sinkron health to check if Sinkron platform is active instead of viewing config.
• Rotate tokens periodically and after any suspected exposure.
• Restrict shell history after setting tokens (HISTCONTROL=ignorespace or read -s).
• Test in an isolated environment before production deployment.

Observability Recommendations

Log: health status, message counts, deletion results.

Do NOT log: tokens, email contents, sensitive metadata.

CLI Commands

Health Check

sinkron health

Register New Agent

sinkron register --username USER --name NAME

SINKRON_TOKEN is issued here. The Sinkron backend generates and prints the token once in the response. Copy it immediately and store securely. Do not run in logged or shared environments. `` Registration successful. username: myagent email: myagent@sinkron.id token: snk_xxxxxxxxxxxxxxxxxxxxxxxx ← copy immediately, store securely ` Existing agents with a prior token: skip this step, set SINKRON_TOKEN` directly.

Get Inbox

sinkron inbox [--page N] [--search KEYWORD]

Check Email Exists

sinkron check ADDRESS

Get Message

sinkron message ID

Delete Messages

sinkron delete-messages --ids 1,2,3

Delete Inbox

sinkron delete-inbox [--force]

Get Agent Info

sinkron agent USERNAME

Check Platform Status

# Use this command to check if Sinkron platform is active
sinkron health

Set Token

# Always load from environment variable
sinkron config --token "$SINKRON_TOKEN"

Clear Token

sinkron config --clear-token

Automation Patterns

Minimal Safe Workflow

sinkron health || exit 1
sinkron inbox --page 1

Safe Deletion Pattern

sinkron inbox --search "alert"
# Review IDs before deleting
sinkron delete-messages --ids 10,11

Failure Handling Strategy

1. Authentication error → prompt token reconfiguration via SINKRON_TOKEN env var.
2. Network error → retry with exponential backoff.
3. Empty inbox → return structured empty response.
4. Invalid ID → prompt verification.

Fail predictably. Avoid silent errors.

Production Readiness Checklist

• [ ] Provenance verified: homepage, GitHub repo, PyPI owner all confirmed
• [ ] Package source code inspected (no unexpected network callbacks or telemetry)
• [ ] Pinned version used during install
• [ ] Tested in isolated environment (container/VM) first
• [ ] sinkron --help confirms installation
• [ ] SINKRON_TOKEN obtained from sinkron register output (new) or prior registration (existing)
• [ ] Token stored in secret manager or restricted env var immediately after registration
• [ ] Shell history cleared after token was displayed
• [ ] Token not present in logs, CI output, or version-controlled files
• [ ] sinkron health integrated at workflow start (check if platform is active)
• [ ] sinkron health || exit 1 integrated at workflow start
• [ ] Logging sanitized (no tokens, no sensitive metadata)
• [ ] Retry strategy implemented
• [ ] Safe deletion logic confirmed (no blind bulk deletes)

Conclusion

This skill provides permanent email identity and inbox automation for AI agents via the Sinkron platform.

SINKRON_TOKEN is self-issued by the Sinkron backend at registration — not by any third party. When used with verified provenance, pinned versions, secure token handling, and controlled deletion flows, this skill is production-safe and automation-ready.

If package provenance cannot be confirmed, do not install. Treat the skill as untrusted until source verification is complete.