Profile manual

Importing profiles

A profile from another app becomes a Pipe profile when you add it: Pipe converts it. Surge profiles, Clash and mihomo configurations, and sing-box configurations all go through the converter, each as far as Pipe's format can say what it says — proxies, groups, rules and rule sets, DNS and hosts. What you then have is a Pipe profile: the format this manual describes, and the one to write a profile of your own in. A Surge profile converts best, line for line, because Pipe's format began from Surge's; it is still converted, not taken as it is (Surge).

What does not come across is never dropped in silence. It stays in the profile as a comment, and the app lists it before the profile is added — each item saying whether it changes where traffic goes, only how Pipe is set up, or nothing but appearance. A conversion with nothing listed that changes routing is added at once; one with a routing change is shown for review, and so is a profile fetched again whose conversion changes routing in a way the review did not show.

Once converted, the profile says nothing more of the app it came from: what checking it reports (diagnostics) is about the Pipe profile, as of one you wrote.

Adding a profile#

In the app: Profile, the profile's name at the top, then +:

• Paste or Download… takes the text of a profile, or a link to one.
• Open a File takes a file.

Pipe tells the format by the content. When something does not come across, the app shows what was converted — how many proxies, groups and rules — and the list of what was left out or changed, each with why, before the profile is added. A profile with nothing to list is added at once.

A link is fetched as Surge asks for a profile (its User-Agent): providers choose the format they send by it, and a Surge profile is the one that converts most completely. A provider that sends a Clash or sing-box configuration instead is converted all the same, and so is a profile a provider wraps in base64, as it wraps a list of links.

Share links, a subscription of share links (base64), and a WireGuard file are lists of proxies, not profiles: they have no groups or rules to convert. Import those under Profile › All Proxies, into the pool, where every profile can take them in.

Add links#

A link can offer a module, a profile or a subscription to anyone with Pipe, from a web page, a message or another app:

https://getpipe.today/add?module=<url>
https://getpipe.today/add?profile=<url>
https://getpipe.today/add?subscription=<url>

pipe://add?module=<url>, and the same for the other two, says the same thing where a web link would not open the app. Without Pipe, the web link opens a page that says what the link asks for.

Opening a link adds nothing. It opens the sheet you would have typed the address into, with the address filled in and its host named. Pipe fetches nothing until you tap Review, and keeps nothing until you accept the review, as with an address you pasted yourself.

A link holds one address, percent-encoded, and nothing else:

• The address begins with https://, has a host and has no user or password in it.
• It is plain printable text, at most 2,048 bytes, with no spaces.
• Anything else in the link, such as a second address, refuses it. An address left unencoded usually does this: its own & starts another part of the link.

Pipe says it can't use a link it refuses, and does nothing else. A link shows its address to whoever can read the link, and the page for people without Pipe asks getpipe.today for it: keep a subscription's private address out of a link you post where others can see it.

What does not come across#

Each part that Pipe's format has no way to say becomes a comment where it would have been, and a line in the list the app shows:

[Proxy]
Server 1 = trojan, server1.example.com, 443, password=pw
# not converted: proxy 'JP 02' — tls: REALITY public_key must be 43 unpadded URL-safe base64 bytes

[Rule]
# not converted: IP-SUFFIX,1.1.1.1/24,DIRECT — Pipe has no IP-SUFFIX rule
GEOIP,JP,DIRECT

What a conversion writes is checked by Pipe's own compiler before it is given to the app: a profile that does not compile is an error, not a profile. Conversion can change routing where the formats differ; review the reported changes before using it. Unavailable policies are handled as follows:

• A rule whose policy could not be converted — a proxy Pipe cannot run, a group it has no counterpart for — rejects what it matches, with a comment that says why. So does a rule naming a policy the original does not define.
• A group none of whose members could be converted rejects everything: its only member is REJECT.
• A group keeps the members that could be converted, and the list says which it left out. A reference to anything that could not be written — a group, a provider's group, a proxy — is resolved against what was: what dropped it re-renders without it and says so, so nothing dangles.

A rule whose matcher has no counterpart in Pipe is left out, as Pipe leaves out a rule it cannot evaluate: what it would have matched goes on to the rules after it, and the note says so — a routing change, shown for review. A proxy Pipe cannot run yet (Not supported yet) is left out with the reason.

A proxy whose TLS handshake is to look like a browser's — Clash's client-fingerprint, sing-box's utls, a link's fp — gets Chrome's, the one browser handshake Pipe has (client-fingerprint): firefox, safari, ios, edge, random and the rest ask for the same thing, a handshake that passes for a browser's, and Chrome's does. One note, as a setting, names the proxies it changed. none asks for no browser's, and gets none.

Names stay as they were. Two of one name become Server and Server 2. A proxy or group named like a built-in policy (DIRECT, REJECT-DROP, …) can never be reached — everything naming the name reaches the policy, as in mihomo and Surge — so it is skipped with a note, and the rules and members that named it use the policy. A name a profile line cannot say — one that would read as a comment or a section's header — is written quoted, and what cannot be quoted is skipped with the reason.

Kept current#

A profile added from a link is kept current from it when its format says so — and a Clash or sing-box one always, as those apps keep every profile from a link current. The converted profile then begins with a #!MANAGED-CONFIG line naming the link:

#!MANAGED-CONFIG https://provider.example/subscribe?token=… interval=43200 strict=false

The interval is the one the server gives (profile-update-interval, in hours, as Clash subscriptions send it), else a day. A Surge profile is kept current by its own #!MANAGED-CONFIG line, as it says; one without the line is a copy.

Each time the profile is fetched again, what comes back is converted again, the same way. As with every managed profile, what you change in it is replaced at its next update: change it with a module.

Surge#

Nearly every line of a Surge profile is a line of Pipe's format already, and means the same: it is kept as written, with its comments, order and line requirements. What is Surge's alone does not come across:

Each line left out becomes a # not converted: comment where it was, naming it and why — never its value, which may hold a password:

[General]
loglevel = notify
# not converted: hijack-dns — every DNS query sent to port 53 through Pipe's tunnel is answered by Pipe already
skip-proxy = 127.0.0.1, 192.168.0.0/16

Older spellings#

Pipe's format reads one spelling of each thing. Where Surge has another, older one, the conversion writes Pipe's in its place, on the same line, with its comment and line requirement:

A Surge module, when it is added, has its older spellings written the same way (Modules).

What stays and Pipe does not do yet — a proxy it cannot run, a rule option it reads past — is the compiler's to report, as of any profile (diagnostics). A module (#!name=…) is not a profile but a plugin: it is added to a profile the app already has (Modules), not converted as one.

Clash and mihomo#

Proxies#

proxies (and the old Proxy) become [Proxy] lines, field by field, with mihomo's leniency: keys in any case, _ read as -. A proxy's dialer-proxy becomes underlying-proxy. As in mihomo, a Shadowsocks, VMess, VLESS, Trojan, AnyTLS, SOCKS5, Snell or MASQUE proxy carries UDP only with udp: true; without it, its line says udp-relay=false. mihomo's masque is Cloudflare WARP's: it becomes a masque line with mode=cloudflare, its private-key, public-key, ip, ipv6, mtu, uri and sni kept, and its dns with remote-dns-resolve: true; with network: h3-l4proxy, WARP's TCP proxy, a plain line that carries TCP alone. network: h2 is left out. An ssh proxy's key, written in the config (private-key: | and the key's text), becomes a [Keystore] item the line names, and private-key-passphrase comes across as it is; a key named by its file's path is left out, with a note: the file is on the machine the config was written for, which Pipe cannot read.

Groups#

Proxy providers#

Each provider a group uses becomes a hidden select group of its own, named like the provider, at the end of [Proxy Group]. The groups that use it take its members in with include-other-group.

Rules#

DIRECT, REJECT and REJECT-DROP are Pipe's built-in policies of those names, and COMPATIBLE is DIRECT. GLOBAL is the config's own group of that name when it has one; otherwise it is mihomo's own group of every proxy, which Pipe does not have, and is DIRECT — what that group has picked until someone picks another. A rule whose policy is PASS does nothing in Clash, and is left out.

Rule providers#

DNS and hosts#

Everything else#

sing-box#

Outbounds#

Rules#

A sing-box rule matches when one of its destinations does — domain, domain_suffix, domain_keyword, domain_regex, ip_cidr, ip_is_private, rule_set — and every other condition holds too: a port, a source, the network, and the rest. Pipe writes it so:

• A rule of destinations alone becomes one line per destination, each with the rule's policy.
• Any other becomes one logical rule: AND,((OR,((DOMAIN,a.example),(DOMAIN,b.example))),(DEST-PORT,443)),Proxy.
• invert is NOT; a logical rule (type: logical, mode: and or or) is AND or OR of its rules, nested ten deep at most. Each value is written as a rule's is, quoted where it holds a comma or a parenthesis: a pattern's {1,3} or an SSID's comma stays in it.
• A rule set a rule names that cannot be read narrows the rule when some of the others survive (with the note where the set is); when none do — or under invert, where dropping one would widen what the rule matches — the whole rule is left out rather than broadened to its other conditions. The note says so.

Terminal route actions can override the connection's destination while keeping the selected proxy or group and the original match metadata (Destination overrides). Nonterminal address/port options continue through later matching rules and apply to the selected terminal policy or FINAL. UDP timeouts, TLS fragmentation and network strategies follow native route controls, including their duration, stream and host-interface limits. Imported network_type remains a matcher, including on route-options, as in sing-box's rule schema. Native network-type is a separate explicit dial filter. Route fallback_delay accepts both documented duration strings and the reference implementation's uint32 nanoseconds. udp_connect, udp_disable_domain_unmapping and TLS spoofing remain unsupported and leave the whole action out. sing-box gives a sniffed domain precedence over the replaced destination; Pipe retains sniffed names for explicit extended-matching, while ordinary domain rules use the effective host. A conversion using both sniffing and nonterminal options reports this remaining distinction.

route.final becomes FINAL, with dns-failed. Without it, FINAL names the first outbound, as sing-box sends what no rule matches there.

Rule sets#

DNS and the rest#

Advanced DNS imports allow at most 256 resolvers, 1,024 rules, 256 KiB of DNS text and 16,384 values. Concurrent conversions share a temporary memory allowance. Exceeding these bounds or the allowance aborts conversion.

Categories#

Clash, mihomo and sing-box name their geodata by category: GEOSITE,google, GEOIP,JP, geosite-cn.srs. A country's addresses are Pipe's own GEOIP, which its built-in table answers for every country. Every other category — every domain category, whatever country it is about — becomes the list of the same category from MetaCubeX's meta-rules-dat, the data mihomo's own geodata is built from, and the list a Pipe profile's GEOSITE names too: fetched and kept current like any rule set. Where the source says where its geodata lives (geox-url, a mirror of the same repository), the lists come from there — a mirror is the point of naming one. Every substitution is noted with the list's URL, for when it does not load.

In a [Host] key, which takes lists only, a GEOSITE category is its list too.

IP-ASN rules need an ASN database: the converted profile's ip-asn-maxmind-url is the one the configuration names (mihomo's geox-url.asn), else meta-rules-dat's GeoLite2-ASN.

[General]
ip-asn-maxmind-url = https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/GeoLite2-ASN.mmdb

[Rule]
RULE-SET,https://raw.githubusercontent.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/category-ads-all.yaml,REJECT
RULE-SET,https://raw.githubusercontent.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/google.yaml,Proxy
RULE-SET,https://raw.githubusercontent.com/MetaCubeX/meta-rules-dat/meta/geo/geoip/telegram.yaml,Proxy,no-resolve
IP-ASN,13335,Proxy,no-resolve
GEOIP,JP,DIRECT
FINAL,Proxy,dns-failed

A converted group whose name filters change meaning after proxy-name collision renaming is rejected with a routing note. The same applies when differently modified copies of a shared subscription make name filters or the selected default ambiguous. Review that group before using the converted profile; static provider filters and known inline defaults use the original source names.