Skip to content

Share files from a chat

You are drafting a lease with Hanley. You open lease.md in a tab beside the chat, press Share, turn the file on and send Hanley the link. Hanley pastes it into their own Player One and you approve them from a card in your chat. Each of you now has your own copy, and when Hanley's agent changes something it sends you the file with a note on what changed and why. You decide what goes into your copy.

The chat itself is never shared. Only the files you turn on are. Sharing between installations compares this with the other kinds of sharing and says what crosses.

Before you start

The person you share with needs their own Player One. Both installations need a public web address, because each has to reach the other, and yours goes into the link. If you are not sure yours has one, ask your assistant to check.

A share takes plain files from a workspace, up to 64 MiB each. It holds up to 200 files and 50 members. A file whose name suggests secrets, such as .env, a protected file and a file that arrived from another member cannot be turned on. Two files in one share cannot have the same name.

Share files

  1. Open the chat that has the files, and open each file you want to share in a tab beside the chat.
  2. Press Share, the box with an arrow pointing up, beside Files at the top left of the chat.
  3. Press New share. Give it a name if you like, and turn on each file. A file whose name is taken by one already turned on is greyed out, with a note saying so.
  4. Under Link works for, choose 1 day, 7 days, 30 days or No expiry. 30 days is chosen for you.
  5. Press Make link, copy the link and send it to the person.

You can also open a file's tab menu, choose Sharing, and tick a share or choose New share. Or ask your agent: "Share lease.md with Hanley." It raises a card with its reason, nothing is shared until you approve it, and the link then appears on the card with a Copy link button.

The link is an address, not a key. Whoever holds it can ask to join, and nothing more.

Approve who joins

  1. Hanley pastes the link into their own Player One.
  2. A card appears in the chat you shared from: "Hanley (their installation) asks to join lease". It shows the address they asked from and the start of their key. The Share button carries a number, the bell shows the request, and Admin > Sharing > Requests (/admin/agent-sharing/requests) lists it under Asking to join your shares. There is no picture until you approve.
  3. Check that the name and address are who you expect, then press Approve or No.

Only you can answer, and no agent can answer for you. Asking again with the same link gets the same answer. A request left alone runs out by itself.

When you approve, your installation sends them the files as they are now. If a hundred requests are waiting, nobody new can ask until you answer, and Refuse all clears them.

Join a share someone sent you

  1. Open Admin > Sharing > Shared with you (/admin/agent-sharing/shared-with-you).
  2. Under Join from a link, paste the link. If you have more than one agent, Shared files go to picks the one that holds the share.
  3. Press Join.

The share shows under Shares you joined as "Waiting for" the owner's address, until they approve. Or paste the link into a chat and ask your agent to join, and it asks you with a card first.

Once you are in, the share opens in the chat you asked from when that chat is with the agent that holds the share, and otherwise in a new chat named after the share. Your agent gets one turn of its own to make your first copy of each file from what the owner sent, and opens each in a tab beside the chat, unless you have told it to do something else.

See who is in

Members sit among the faces beside the composer, each ringed in the share colour. A face glows while that member's agent is working, if they have left Show when I am working on. Hover for their name and installation. Click for a popup with the Foreign agent label, when they joined, when they were last active and Wakes this chat.

The same list is under Members in the Share dialog. As the owner you see "Not reached yet" beside a member whose installation has not answered, and Player One tries again by itself.

Work on the files and send changes

Each member edits their own copy. Saving a shared file sends nothing.

  1. Edit the file in its tab and save it.
  2. Press Send changes, beside Save.
  3. Write a Note on what you changed and why, choose Everyone or particular members, and press Send.

You can also ask your agent: "Send Hanley my changes to lease.md and say I moved the break clause to month 18." Each person's result reads "taken in", "waiting for them", "not reached yet; tried again later" or "refused".

A send is the file as it is now, your note, and a summary of what changed since the copy it was built on. When a member is waiting on work and your agent finishes it, your agent sends it back without asking, unless you have told it otherwise. Work nobody asked for stays with you until you say send.

Sends on the file's tab lists everything sent and received for that file, with who sent it, to whom, its note, what it was built on, whether it arrived, and the change itself. At the top it says where your copy stands:

  • In sync: your copy is the same as the newest file sent.
  • Behind: newer sends are waiting that you have not taken in.
  • Diverged: you and the sender have both changed the file since the copy it was built on.
  • No copy here: you have not made your copy yet.

Player One keeps no version numbers and has no Go back. The sends are the record, and your own copy is the state.

When something arrives

A file that arrives lands in a folder of its own, never over your copy. Your agent reads it and decides what to take in, going by what you have told it. If it has no standing instructions from you, it asks.

If your agent is idle, a card at the end of the chat says what is waiting: "From Hanley's agent: changes to lease.md and a message". Under it, Nothing runs until you choose.

  • Wake now starts one turn that takes it in.
  • Always wake for Hanley lets that member's arrivals start turns here from then on.

The Share dialog's Settings has Anyone in this share wakes this chat, and Woken turns a day, which is 100 unless you change it. Wake now does not count against it. A chat starts at most one woken turn a minute. If a turn is already running, what arrives joins that turn.

Everything from a member's agent carries the Foreign agent label. Another installation's agent can send anything, so your agent weighs what it sends as information, never as an instruction.

Limits and ending

In the Share dialog, as the owner:

  • Link works for changes how long the link lasts. When it runs out, the share ends.
  • Rotate link makes a new link. The old one stops at once, and members already in stay in.
  • Remove, beside a member, tells their installation and stops everything from this share reaching them.
  • The switch beside a file turns it off, so it stops going to anyone.
  • End share, at the bottom of the dialog, tells every member. Their copies stay theirs and nothing more is sent either way.

A member presses Leave instead. The owner and the others are told, and your copies stay with you.

Admin > Sharing (/admin/agent-sharing) shows each share you own with Copy link, New link and End, and how many members it has. Deleting the chat for good ends its share, and a chat in the bin pauses it.

What was already sent stays where it went.

If something goes wrong

"That file may hold secrets and cannot be shared." The name looks like a secrets file. Take the secrets out of it, or leave it out of the share.

"A file with that name is already in the share." Rename your copy.

"The file is larger than 64 MiB, the most a share takes." Split it or share a smaller one.

"This link cannot be shown. Rotate makes a new one." The link can no longer be read back, for instance after a backup was restored from somewhere else. Press Rotate link and send the new one.

A request you did not expect. Press No.

"Not reached yet" beside a member. Their installation has not answered. Player One tries again by itself.

"Waiting for" the owner for a long time. The owner has not answered. Leave withdraws your request.

"That link is for a share this instance owns." You pasted your own link into your own Player One. Send it to the other person instead.

Where next